openapi: 3.1.0
info:
  title: Lexabit API
  version: v1
  description: >-
    The Lexabit REST API (v1) for compliance and financial intelligence.
    Authenticate with a bearer token (Laravel Sanctum). All endpoints are
    versioned under `/{service}/v1`.


    **Environments:** `https://api.lexabit.com` is production — only for
    applications running against the live environment. For all development,
    testing, and integration work use `https://api.staging.lexabit.com` (same
    API, separate data and credentials).


    Access-model fields such as `sponsored`, `delegated`, apps, and connectors
    are named differently in the Lexabit Portal than in this reference. [Access
    Concepts & Portal
    Terms](https://docs.lexabit.com/docs/concepts/access-vocabulary/) maps each
    one to the exact wording your users see.
  contact:
    name: Lexabit Support
    url: https://lexabit.com
servers:
  - url: https://api.lexabit.com
    description: >-
      Production — only for applications running against the live production
      environment
  - url: https://api.staging.lexabit.com
    description: Staging — use this for all development, testing, and integration work
security:
  - http: []
paths:
  /accounttracking/v1/accounts/{accountId}/report:
    get:
      operationId: accounttracking.v1.accounts.report
      description: |-
        Generate a full PDF report for a tracked account.

        Returns binary application/pdf — not the standard {data,meta} envelope.
        This endpoint does not support the Idempotency-Key header.
      summary: Generate a full PDF account report
      tags:
        - AccountReportV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
        - name: from_date
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date
        - name: to_date
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date
        - name: include_charts
          in: query
          schema:
            type: boolean
        - name: template
          in: query
          schema:
            type: string
            enum:
              - default
              - compliance
              - overview
        - name: filename
          in: query
          schema:
            type: string
            maxLength: 255
        - name: charts
          in: query
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                  maxLength: 60
                image_base64:
                  type: string
          x-deepObject-style: qs
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    const: Not found
                required:
                  - message
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/accounts/{accountId}/transactions/{transactionId}/pdf:
    get:
      operationId: accounttracking.v1.accounts.transactions.pdf
      description: |-
        Generate a single-transaction PDF slip.

        Returns binary application/pdf — not the standard {data,meta} envelope.
        This endpoint does not support the Idempotency-Key header.
      summary: Generate a single-transaction PDF slip
      tags:
        - AccountReportV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
        - name: filename
          in: query
          schema:
            type: string
            maxLength: 255
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    const: Not found
                required:
                  - message
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageBag'
  /accounttracking/v1/accounts/{accountId}/transactions/bulk-pdf:
    post:
      operationId: accounttracking.v1.accounts.transactions.bulk-pdf
      description: >-
        Generate a bulk PDF for a user-selected set of transactions on a single
        account.


        Takes the route {accountId} (per-account, not multi-account). Requires

        transactionIds (array, min 1, max 100, each a string). Restricted to

        accounts within the caller's current scope. The response includes

        summary statistics for the included transactions.


        SPECIAL SURFACE: binary application/pdf — NOT {data,meta}.

        Idempotency is not supported for this route.
      summary: Generate a bulk transaction PDF
      tags:
        - AccountReportV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filename:
                  type:
                    - string
                    - 'null'
                  maxLength: 255
                transactionIds:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
              required:
                - transactionIds
      responses:
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      message:
                        type: string
                        const: No transactions found
                    required:
                      - message
                  - type: object
                    properties:
                      message:
                        type: string
                        const: Not found
                    required:
                      - message
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    const: Failed to fetch transactions
                required:
                  - message
  /accounttracking/v1/accounts/{id}/settings:
    patch:
      operationId: accounttracking.v1.accounts.settings
      description: >-
        Update per-account feature settings (autoSyncEnabled,
        counterpartScanningEnabled, etc.).

        Returns the updated settings, available settings, and backfill status.
      summary: Update per-account feature settings
      tags:
        - AccountSettingsV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountSettingsV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      settings:
                        type: string
                      availableSettings:
                        type: array
                        items: {}
                      backfillStatus:
                        type: object
                        properties:
                          last_backfill: {}
                          counterparts_needing_enrichment:
                            type: string
                          total_counterparts:
                            type: string
                        required:
                          - last_backfill
                          - counterparts_needing_enrichment
                          - total_counterparts
                    required:
                      - settings
                      - availableSettings
                      - backfillStatus
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/accounts/{id}/tracking-start-date:
    patch:
      operationId: accounttracking.v1.accounts.tracking-start-date
      description: Update the scope's visibility floor and trigger backfill if needed.
      summary: Update the tracking start date
      tags:
        - AccountSettingsV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTrackingStartDateV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      tracking_start_date:
                        type: string
                      previous_tracking_start_date:
                        type: string
                      earliest_booking: {}
                      backfill_dispatched:
                        type: boolean
                    required:
                      - tracking_start_date
                      - previous_tracking_start_date
                      - earliest_booking
                      - backfill_dispatched
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/accounts/{accountId}/counterpart-scan:
    post:
      operationId: accounttracking.v1.accounts.counterpart-scan
      description: |-
        Trigger a counterpart backfill scan for an account.

        Dry-run (dryRun=true): returns stats without dispatching.
        A live run dispatches a background scan and returns 202.

        This endpoint does not support the Idempotency-Key header: re-sending
        dispatches a new scan.
      summary: Trigger a counterpart backfill scan
      tags:
        - AccountSettingsV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CounterpartScanV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      transactionsWithoutEntity:
                        type: string
                      totalCounterparts:
                        type: integer
                      counterpartsNeedingEnrichment:
                        type: integer
                      counterpartsAlreadyEnriched:
                        type: string
                      fromDate:
                        type:
                          - string
                          - 'null'
                      toDate:
                        type: string
                    required:
                      - transactionsWithoutEntity
                      - totalCounterparts
                      - counterpartsNeedingEnrichment
                      - counterpartsAlreadyEnriched
                      - fromDate
                      - toDate
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      jobDispatched:
                        type: boolean
                      message:
                        type: string
                        const: Backfill scan job dispatched
                    required:
                      - jobDispatched
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/banks:
    get:
      operationId: accounttracking.v1.banks
      description: >-
        Catalog of available banks (slow-changing reference data).

        Returns a paginated collection. Responses include an ETag for
        conditional requests.
      summary: List available banks
      tags:
        - AccountV1
      parameters:
        - name: countryCode
          in: query
          schema:
            type: string
        - name: accountType
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        countryCode:
                          type: string
                        bankingGroupName:
                          type: 'null'
                        bankDisplayName:
                          type: string
                        bankOfficialName:
                          type: string
                        bic:
                          type:
                            - string
                            - 'null'
                        status:
                          type: string
                          const: AVAILABLE
                        logo_url:
                          type:
                            - string
                            - 'null'
                        requires_psu_id:
                          type: boolean
                        beta:
                          type: boolean
                        maximum_consent_validity:
                          type:
                            - string
                            - 'null'
                        supported_auth_approaches:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                              minItems: 0
                              maxItems: 0
                              additionalItems: false
                        supported_services:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                              minItems: 0
                              maxItems: 0
                              additionalItems: false
                        psu_types:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                              minItems: 0
                              maxItems: 0
                              additionalItems: false
                        popularity_rank:
                          type:
                            - integer
                            - 'null'
                      required:
                        - id
                        - countryCode
                        - bankingGroupName
                        - bankDisplayName
                        - bankOfficialName
                        - bic
                        - status
                        - logo_url
                        - requires_psu_id
                        - beta
                        - maximum_consent_validity
                        - supported_auth_approaches
                        - supported_services
                        - psu_types
                        - popularity_rank
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type: integer
                          currentPage:
                            type: integer
                            const: 1
                          lastPage:
                            type: integer
                            const: 1
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/supported-countries:
    get:
      operationId: accounttracking.v1.supported-countries
      description: |-
        List of supported country codes from active integrations.
        Responses include an ETag for conditional requests.
      summary: List supported country codes
      tags:
        - AccountV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      countries:
                        type: object
                        description: >-
                          Countries we can actually serve banks for — those with
                          at least one

                          active row in bank_registry that has Enable Banking
                          provider_data.
                        additionalProperties: {}
                    required:
                      - countries
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/active:
    get:
      operationId: accounttracking.v1.active
      description: |-
        Whether the current user is registered and active for account tracking.
        Returns 200 whether or not the user is active.
      summary: Check whether the user is active for account tracking
      tags:
        - AccountV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      active:
                        type: boolean
                      message:
                        type: string
                        enum:
                          - User is registered and active for Account Tracking
                          - >-
                            User is NOT registered and active for Account
                            Tracking
                    required:
                      - active
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/users:
    post:
      operationId: accounttracking.v1.users.register
      description: >-
        Register the current user for account tracking (D11 — pre-activation
        step).
      summary: Register the current user for account tracking
      tags:
        - AccountV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/consents/{consentId}/accounts:
    get:
      operationId: accounttracking.v1.consents.accounts
      description: List accounts available for a specific consent.
      summary: List accounts available for a consent
      tags:
        - AccountV1
      parameters:
        - name: consentId
          in: path
          required: true
          schema:
            type: integer
        - name: scopeEntityId
          in: query
          schema:
            type: string
        - name: scopeEntityType
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      consent_id:
                        type: integer
                      consent_status:
                        type: string
                      integration:
                        type: string
                      owner_entity_id:
                        type: string
                      owner_entity_type:
                        type: string
                      accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            account_id:
                              type:
                                - string
                                - 'null'
                            account_name:
                              type:
                                - string
                                - 'null'
                            display_name:
                              type:
                                - string
                                - 'null'
                            iban:
                              type:
                                - string
                                - 'null'
                            bban:
                              type:
                                - string
                                - 'null'
                            account_number:
                              type:
                                - string
                                - 'null'
                            currency:
                              type:
                                - string
                                - 'null'
                              description: '''bank_name'' => $normalizedAccount[''bank_name''],'
                            account_type:
                              type:
                                - string
                                - 'null'
                            tracking_status:
                              type: string
                              enum:
                                - tracked
                                - new
                          required:
                            - account_id
                            - account_name
                            - display_name
                            - iban
                            - bban
                            - account_number
                            - currency
                            - account_type
                            - tracking_status
                      summary:
                        type: object
                        properties:
                          total_accounts:
                            type: integer
                          tracked_accounts:
                            type: integer
                          new_accounts:
                            type: integer
                        required:
                          - total_accounts
                          - tracked_accounts
                          - new_accounts
                      consent_info:
                        type: object
                        properties:
                          granted_at:
                            type: string
                          expires_at:
                            type: string
                          remaining_days:
                            type: string
                          scope:
                            type: string
                        required:
                          - granted_at
                          - expires_at
                          - remaining_days
                          - scope
                    required:
                      - consent_id
                      - consent_status
                      - integration
                      - owner_entity_id
                      - owner_entity_type
                      - accounts
                      - summary
                      - consent_info
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/accounts/{id}/purge-preview:
    get:
      operationId: accounttracking.v1.accounts.purge-preview
      description: >-
        Preview the impact of a purge. Available to anyone with
        accounttracking.delete.

        can_force_full flag tells the client whether NukeEverything is
        available.
      summary: Preview the impact of a purge
      tags:
        - AccountV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      physical_account_id:
                        type:
                          - integer
                          - 'null'
                      other_tracker_count:
                        type: integer
                      is_last_tracker:
                        type: string
                      transaction_count:
                        type: integer
                      linked_counterpart_count:
                        type: integer
                      sync_running:
                        anyOf:
                          - type: string
                          - type: boolean
                      can_force_full:
                        type: boolean
                    required:
                      - physical_account_id
                      - other_tracker_count
                      - is_last_tracker
                      - transaction_count
                      - linked_counterpart_count
                      - sync_running
                      - can_force_full
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/accounts/{id}/purge:
    post:
      operationId: accounttracking.v1.accounts.purge
      description: |-
        Destructively purge (hard delete) a tracked account.

        Authorization is per-mode:
         - smart_untrack_unless_last: requires the accounttracking.delete permission,
           and the account must be within the caller's current scope.
         - nuke_everything: restricted to administrators.
      summary: Hard-delete a tracked account
      tags:
        - AccountV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurgeAccountV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    anyOf:
                      - type: object
                        properties:
                          physical_accounts: {}
                          tracked_accounts: {}
                          transactions:
                            type: integer
                          counterparts: {}
                          merged_views:
                            type: integer
                          sessions_scrubbed:
                            type: integer
                        required:
                          - physical_accounts
                          - tracked_accounts
                          - transactions
                          - counterparts
                          - merged_views
                          - sessions_scrubbed
                      - type: object
                        properties:
                          physical_accounts:
                            type: integer
                          tracked_accounts:
                            type: integer
                            enum:
                              - 1
                              - 0
                          transactions:
                            type: integer
                          counterparts:
                            type: integer
                          merged_views:
                            type: integer
                          sessions_scrubbed:
                            type: integer
                        required:
                          - physical_accounts
                          - tracked_accounts
                          - transactions
                          - counterparts
                          - merged_views
                          - sessions_scrubbed
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: sync_in_progress
                      message:
                        type: string
                        const: >-
                          A sync is currently running on this account. Try again
                          once it finishes.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/accounts:
    get:
      operationId: accounttracking.v1.accounts.index
      description: |-
        List tracked accounts for the current actor/scope.
        Returns page-paginated ApiCollection + PagePaginationMeta.
      summary: List tracked accounts for the current scope
      tags:
        - AccountV1
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: sort
          in: query
          schema:
            type: string
        - name: filter[q]
          in: query
          schema:
            type: string
        - name: filter[status]
          in: query
          schema:
            type: string
        - name: filter[bankId]
          in: query
          schema:
            type: string
        - name: filter[countryCode]
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: filter[accountType]
          in: query
          schema:
            type: string
            enum:
              - private
              - company
              - payment
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        accountNumber:
                          type: string
                        bankId:
                          type: string
                        bankName:
                          type: string
                        bic:
                          type: string
                        bban:
                          type: string
                        currency:
                          type:
                            - string
                            - 'null'
                        countryCode:
                          type: string
                        accountType:
                          type:
                            - string
                            - 'null'
                        ownerName:
                          type: string
                        grossAmount:
                          anyOf:
                            - type: number
                            - type: string
                        balance:
                          type:
                            - object
                            - 'null'
                          description: >-
                            Bank-reported balance with freshness — null until
                            the first

                            transaction sync stores a snapshot.
                          properties:
                            amount:
                              type: number
                            currency:
                              type: string
                            type:
                              type: string
                            referenceDate:
                              type:
                                - string
                                - 'null'
                              description: >-
                                Nullable: the provider may report a balance
                                without a

                                reference date.
                            fetchedAt:
                              type: string
                          required:
                            - amount
                            - currency
                            - type
                            - referenceDate
                            - fetchedAt
                        status:
                          type: string
                        isActive:
                          type: boolean
                        partnerAccountStatus:
                          type: string
                        referenceId:
                          type: string
                        lastTransactionSync:
                          type: string
                        physicalAccountId:
                          type: string
                        scopeEntityType:
                          type: string
                        scopeEntityId:
                          type:
                            - string
                            - 'null'
                        scopeName:
                          type:
                            - string
                            - 'null'
                        autoSyncEnabled:
                          type: boolean
                        counterpartScanningEnabled:
                          type: boolean
                        blacklistCheckingEnabled:
                          type: boolean
                        accountIntelligenceEnabled:
                          type: boolean
                        scopeOrigin:
                          type: object
                          description: >-
                            Nested scope-origin block the list grid reads
                            (scopeOrigin.isInherited

                            drives the direct/inherited split + lock icon).
                          properties:
                            scopeEntityId:
                              type:
                                - string
                                - 'null'
                            scopeEntityType:
                              type: string
                            scopeEntityName:
                              type:
                                - string
                                - 'null'
                            isInherited:
                              type: boolean
                            physicalAccountId:
                              type: string
                          required:
                            - scopeEntityId
                            - scopeEntityType
                            - scopeEntityName
                            - isInherited
                            - physicalAccountId
                        latestSyncRun:
                          description: >-
                            Embedded last sync run for the list-view sync-status
                            badge (only

                            present when the relation is eager-loaded — it is on
                            the list).
                          anyOf:
                            - type: object
                              properties:
                                id:
                                  type: string
                                status:
                                  type: string
                                totalTransactions:
                                  type: string
                                transactionsSynced:
                                  type: string
                                detailsFailed:
                                  type: string
                                startedAt:
                                  type: string
                                completedAt:
                                  type: string
                              required:
                                - id
                                - status
                                - totalTransactions
                                - transactionsSynced
                                - detailsFailed
                                - startedAt
                                - completedAt
                            - type: 'null'
                            - type: object
                        settings:
                          type:
                            - string
                            - 'null'
                        availableSettings:
                          type:
                            - string
                            - 'null'
                        backfillStatus:
                          type:
                            - string
                            - 'null'
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - name
                        - accountNumber
                        - bankId
                        - bankName
                        - bic
                        - bban
                        - currency
                        - countryCode
                        - accountType
                        - ownerName
                        - grossAmount
                        - balance
                        - status
                        - isActive
                        - partnerAccountStatus
                        - referenceId
                        - lastTransactionSync
                        - physicalAccountId
                        - scopeEntityType
                        - scopeEntityId
                        - scopeName
                        - autoSyncEnabled
                        - counterpartScanningEnabled
                        - blacklistCheckingEnabled
                        - accountIntelligenceEnabled
                        - scopeOrigin
                        - latestSyncRun
                        - settings
                        - availableSettings
                        - backfillStatus
                        - createdAt
                        - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type: integer
                          currentPage:
                            type: integer
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
    post:
      operationId: accounttracking.v1.accounts.store
      description: |-
        Add (discover + track) a bank account.
        Returns 201 + Location header.
      summary: Discover and track a bank account
      tags:
        - AccountV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAccountV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: accounttracking.v1.accounts.destroy-multiple
      description: |-
        Bulk delete tracked accounts.
        Returns { data: { deleted: [...] }, meta: { requestId } }.
      summary: Bulk-delete tracked accounts
      tags:
        - AccountV1
      parameters:
        - name: ids[]
          in: query
          schema:
            type: array
            items:
              type: integer
              minimum: 1
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: object
                        additionalProperties: {}
                    required:
                      - deleted
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/accounts/{id}:
    get:
      operationId: accounttracking.v1.accounts.show
      description: >-
        Fetch a single tracked account with settings, availableSettings,
        backfillStatus.

        Returns ETag + Cache-Control: private.
      summary: Fetch a single tracked account
      tags:
        - AccountV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      accountNumber:
                        type: string
                      bankId:
                        type: string
                      bankName:
                        type: string
                      bic:
                        type: string
                      bban:
                        type: string
                      currency:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type: string
                      accountType:
                        type:
                          - string
                          - 'null'
                      ownerName:
                        type: string
                      grossAmount:
                        anyOf:
                          - type: number
                          - type: string
                      balance:
                        type:
                          - object
                          - 'null'
                        description: >-
                          Bank-reported balance with freshness — null until the
                          first

                          transaction sync stores a snapshot.
                        properties:
                          amount:
                            type: number
                          currency:
                            type: string
                          type:
                            type: string
                          referenceDate:
                            type:
                              - string
                              - 'null'
                            description: >-
                              Nullable: the provider may report a balance
                              without a

                              reference date.
                          fetchedAt:
                            type: string
                        required:
                          - amount
                          - currency
                          - type
                          - referenceDate
                          - fetchedAt
                      status:
                        type: string
                      isActive:
                        type: boolean
                      partnerAccountStatus:
                        type: string
                      referenceId:
                        type: string
                      lastTransactionSync:
                        type: string
                      physicalAccountId:
                        type: string
                      scopeEntityType:
                        type: string
                      scopeEntityId:
                        type:
                          - string
                          - 'null'
                      scopeName:
                        type:
                          - string
                          - 'null'
                      autoSyncEnabled:
                        type: boolean
                      counterpartScanningEnabled:
                        type: boolean
                      blacklistCheckingEnabled:
                        type: boolean
                      accountIntelligenceEnabled:
                        type: boolean
                      scopeOrigin:
                        type: object
                        description: >-
                          Nested scope-origin block the list grid reads
                          (scopeOrigin.isInherited

                          drives the direct/inherited split + lock icon).
                        properties:
                          scopeEntityId:
                            type:
                              - string
                              - 'null'
                          scopeEntityType:
                            type: string
                          scopeEntityName:
                            type:
                              - string
                              - 'null'
                          isInherited:
                            type: boolean
                          physicalAccountId:
                            type: string
                        required:
                          - scopeEntityId
                          - scopeEntityType
                          - scopeEntityName
                          - isInherited
                          - physicalAccountId
                      latestSyncRun:
                        description: >-
                          Embedded last sync run for the list-view sync-status
                          badge (only

                          present when the relation is eager-loaded — it is on
                          the list).
                        anyOf:
                          - type: object
                            properties:
                              id:
                                type: string
                              status:
                                type: string
                              totalTransactions:
                                type: string
                              transactionsSynced:
                                type: string
                              detailsFailed:
                                type: string
                              startedAt:
                                type: string
                              completedAt:
                                type: string
                            required:
                              - id
                              - status
                              - totalTransactions
                              - transactionsSynced
                              - detailsFailed
                              - startedAt
                              - completedAt
                          - type: 'null'
                          - type: object
                      settings:
                        type:
                          - string
                          - 'null'
                      availableSettings:
                        type:
                          - string
                          - 'null'
                      backfillStatus:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - accountNumber
                      - bankId
                      - bankName
                      - bic
                      - bban
                      - currency
                      - countryCode
                      - accountType
                      - ownerName
                      - grossAmount
                      - balance
                      - status
                      - isActive
                      - partnerAccountStatus
                      - referenceId
                      - lastTransactionSync
                      - physicalAccountId
                      - scopeEntityType
                      - scopeEntityId
                      - scopeName
                      - autoSyncEnabled
                      - counterpartScanningEnabled
                      - blacklistCheckingEnabled
                      - accountIntelligenceEnabled
                      - scopeOrigin
                      - latestSyncRun
                      - settings
                      - availableSettings
                      - backfillStatus
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /apps/v1/{app}/client-credentials:
    post:
      operationId: apps.v1.client-credentials.store
      summary: Issue the app's client-credentials
      tags:
        - AppClientCredentialV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreAppClientCredentialRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      clientId:
                        type: string
                      clientSecret:
                        type: string
                      name:
                        type:
                          - string
                          - 'null'
                        description: >-
                          shown ONCE — store immediately; null for a public
                          client
                      createdAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - clientId
                      - clientSecret
                      - name
                      - createdAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: apps.v1.client-credentials.destroy
      summary: Revoke the app's
      tags:
        - AppClientCredentialV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /apps/v1/{app}/client-credentials/rotate:
    post:
      operationId: apps.v1.client-credentials.rotate
      summary: Replace the app's
      tags:
        - AppClientCredentialV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      clientId:
                        type: string
                      clientSecret:
                        type: string
                      name:
                        type:
                          - string
                          - 'null'
                        description: >-
                          shown ONCE — store immediately; null for a public
                          client
                      createdAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - clientId
                      - clientSecret
                      - name
                      - createdAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /apps/v1/{app}/keys:
    post:
      operationId: apps.v1.keys.store
      summary: Issue a new key (max 2 active per app)
      tags:
        - AppKeyV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreAppKeyRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/NewAccessToken'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /apps/v1/{app}/keys/{keyId}/rotate:
    post:
      operationId: apps.v1.keys.rotate
      summary: Issue a new key, revoke the old one
      tags:
        - AppKeyV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: keyId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/NewAccessToken'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /apps/v1/{app}/keys/{keyId}:
    delete:
      operationId: apps.v1.keys.destroy
      summary: Revoke a key. 204 on success, 404 if not found
      tags:
        - AppKeyV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: keyId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /apps/v1/{app}/roles:
    get:
      operationId: apps.v1.roles.index
      summary: List the app's active role assignments across
      tags:
        - AppRoleV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppRoleResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: apps.v1.roles.store
      summary: Grant the app a role on a target entity
      tags:
        - AppRoleV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreAppRoleRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Role assigned to app.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: apps.v1.roles.destroy
      summary: Revoke a role. Body carries entityType/entityId/roleKey
      tags:
        - AppRoleV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: entityType
          in: query
          schema:
            type: string
        - name: entityId
          in: query
          schema:
            type: string
        - name: roleKey
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        enum:
                          - Role revoked from app.
                          - Role not found on app.
                      revoked:
                        type: boolean
                    required:
                      - message
                      - revoked
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_failed
                      message:
                        type: string
                        const: entityType, entityId, and roleKey are required.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /apps/v1/whoami:
    get:
      operationId: apps.v1.whoami
      summary: The authenticated actor's identity — works for both User and ApiApp
      tags:
        - AppV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      actorType:
                        type: string
                        const: user
                      actorId:
                        type: string
                      name:
                        type: string
                      status:
                        type: string
                    required:
                      - actorType
                      - actorId
                      - name
                      - status
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /apps/v1:
    get:
      operationId: apps.v1.index
      description: >-
        No route parameter exists for a collection endpoint, so
        entity.permission

        cannot gate it — authorization happens in-controller, exactly like

        ClientController::index.
      summary: List all apps parented to the active scope (X-Scope). Supports
      tags:
        - AppV1
      parameters:
        - name: filter[origin]
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppListResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: apps.v1.store
      description: >-
        Mirrors ClientController::store: validate -> AppService::create() ->

        201 with AppResource + the first key if requested (createKey defaults
        true).
      summary: Create a new App anchored at the operating scope (X-Scope)
      tags:
        - AppV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreAppRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      status:
                        type: string
                      createdBy:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      connectorId:
                        type: string
                      delegated:
                        type: string
                        description: >-
                          True when an active connection has delegated a user's
                          visibility

                          to this app, allowing it to act on that user's behalf
                          within the

                          connected scope.
                      entity:
                        type:
                          - object
                          - 'null'
                        description: >-
                          The entity this app is bound to (its member-edge
                          parent) — lets

                          the admin surface + link to the owning entity. Null if
                          unparented.
                        properties:
                          type:
                            type: string
                          id:
                            type: string
                          name:
                            type:
                              - string
                              - 'null'
                        required:
                          - type
                          - id
                          - name
                      keysCount:
                        type: string
                      lastUsedAt:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Most-recent usage across all of the app's keys. This
                          resource

                          already has the tokens relation loaded (see 'keys'
                          below), whose

                          last_used_at values are cast to Carbon, so max()
                          yields a Carbon

                          or null; fall back to a query aggregate (raw string)
                          if not.
                      keys:
                        type: array
                        items:
                          $ref: '#/components/schemas/AppKeyResource'
                      hasClientCredentials:
                        type: boolean
                      clientCredentialClientId:
                        type: string
                      clientCredentialLastUsedAt:
                        type:
                          - string
                          - 'null'
                      clientCredentialType:
                        type:
                          - string
                          - 'null'
                        enum:
                          - confidential
                          - public
                          - null
                      key:
                        $ref: '#/components/schemas/NewAccessToken'
                    required:
                      - id
                      - name
                      - description
                      - status
                      - createdBy
                      - createdAt
                      - updatedAt
                      - connectorId
                      - delegated
                      - entity
                      - keysCount
                      - lastUsedAt
                      - keys
                      - hasClientCredentials
                      - clientCredentialClientId
                      - clientCredentialLastUsedAt
                      - clientCredentialType
                      - key
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /apps/v1/{app}:
    get:
      operationId: apps.v1.show
      summary: Show a single app. Authorization via entity.permission:app,apps.view
      tags:
        - AppV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      status:
                        type: string
                      createdBy:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      connectorId:
                        type: string
                      delegated:
                        type: string
                        description: >-
                          True when an active connection has delegated a user's
                          visibility

                          to this app, allowing it to act on that user's behalf
                          within the

                          connected scope.
                      entity:
                        type:
                          - object
                          - 'null'
                        description: >-
                          The entity this app is bound to (its member-edge
                          parent) — lets

                          the admin surface + link to the owning entity. Null if
                          unparented.
                        properties:
                          type:
                            type: string
                          id:
                            type: string
                          name:
                            type:
                              - string
                              - 'null'
                        required:
                          - type
                          - id
                          - name
                      keysCount:
                        type: string
                      lastUsedAt:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Most-recent usage across all of the app's keys. This
                          resource

                          already has the tokens relation loaded (see 'keys'
                          below), whose

                          last_used_at values are cast to Carbon, so max()
                          yields a Carbon

                          or null; fall back to a query aggregate (raw string)
                          if not.
                      keys:
                        type: array
                        items:
                          $ref: '#/components/schemas/AppKeyResource'
                      hasClientCredentials:
                        type: boolean
                      clientCredentialClientId:
                        type: string
                      clientCredentialLastUsedAt:
                        type:
                          - string
                          - 'null'
                      clientCredentialType:
                        type:
                          - string
                          - 'null'
                        enum:
                          - confidential
                          - public
                          - null
                    required:
                      - id
                      - name
                      - description
                      - status
                      - createdBy
                      - createdAt
                      - updatedAt
                      - connectorId
                      - delegated
                      - entity
                      - keysCount
                      - lastUsedAt
                      - keys
                      - hasClientCredentials
                      - clientCredentialClientId
                      - clientCredentialLastUsedAt
                      - clientCredentialType
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    patch:
      operationId: apps.v1.update
      description: |-
        `status` transitions delegate to AppService::suspend()/reactivate() (the
        only lifecycle-transition entry points); name/description are plain
        column updates, exactly like ClientController::update.
      summary: Update an app's name/description/status. Authorization via
      tags:
        - AppV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAppRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      status:
                        type: string
                      createdBy:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      connectorId:
                        type: string
                      delegated:
                        type: string
                        description: >-
                          True when an active connection has delegated a user's
                          visibility

                          to this app, allowing it to act on that user's behalf
                          within the

                          connected scope.
                      entity:
                        type:
                          - object
                          - 'null'
                        description: >-
                          The entity this app is bound to (its member-edge
                          parent) — lets

                          the admin surface + link to the owning entity. Null if
                          unparented.
                        properties:
                          type:
                            type: string
                          id:
                            type: string
                          name:
                            type:
                              - string
                              - 'null'
                        required:
                          - type
                          - id
                          - name
                      keysCount:
                        type: string
                      lastUsedAt:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Most-recent usage across all of the app's keys. This
                          resource

                          already has the tokens relation loaded (see 'keys'
                          below), whose

                          last_used_at values are cast to Carbon, so max()
                          yields a Carbon

                          or null; fall back to a query aggregate (raw string)
                          if not.
                      keys:
                        type: array
                        items:
                          $ref: '#/components/schemas/AppKeyResource'
                      hasClientCredentials:
                        type: boolean
                      clientCredentialClientId:
                        type: string
                      clientCredentialLastUsedAt:
                        type:
                          - string
                          - 'null'
                      clientCredentialType:
                        type:
                          - string
                          - 'null'
                        enum:
                          - confidential
                          - public
                          - null
                    required:
                      - id
                      - name
                      - description
                      - status
                      - createdBy
                      - createdAt
                      - updatedAt
                      - connectorId
                      - delegated
                      - entity
                      - keysCount
                      - lastUsedAt
                      - keys
                      - hasClientCredentials
                      - clientCredentialClientId
                      - clientCredentialLastUsedAt
                      - clientCredentialType
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: apps.v1.destroy
      summary: 'Destroy an app: revokes all of its keys, removes its access from every'
      tags:
        - AppV1
      parameters:
        - name: app
          in: path
          required: true
          description: The app ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /auth/v1/login:
    post:
      operationId: auth.v1.login
      description: Rate-limited. May require a reCAPTCHA token.
      summary: Authenticate and start a session
      tags:
        - AuthV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          token:
                            type: string
                          tokenType:
                            type: string
                            const: Bearer
                          user:
                            $ref: '#/components/schemas/UserAuthV1Resource'
                        required:
                          - token
                          - tokenType
                          - user
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: string
        '422':
          $ref: '#/components/responses/ValidationException'
        '429':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: too_many_attempts
                      message:
                        type: string
                        const: Too many login attempts. Please try again later.
                      details:
                        type: object
                        properties:
                          retry_after:
                            type: integer
                        required:
                          - retry_after
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Login failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /auth/v1/me:
    get:
      operationId: auth.v1.me
      summary: Return the current authenticated user
      tags:
        - AuthV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserAuthV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve user.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /auth/v1/logout:
    post:
      operationId: auth.v1.logout
      summary: Revoke the current access token
      tags:
        - AuthV1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Logged out successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Logout failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /auth/v1/logout-all:
    post:
      operationId: auth.v1.logout-all
      summary: Revoke all tokens for the user
      tags:
        - AuthV1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Logged out from all devices.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Logout failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /auth/v1/refresh:
    post:
      operationId: auth.v1.refresh
      summary: Issue a new token and revoke the old one
      tags:
        - AuthV1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                      tokenType:
                        type: string
                        const: Bearer
                    required:
                      - token
                      - tokenType
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Token refresh failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /bank/v1/identify:
    post:
      operationId: bank.v1.identify
      summary: Identify bank from IBAN or BBAN
      tags:
        - BankIdentificationV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyBankV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BankIdentifyV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bank_not_found
                      message:
                        type: string
                        const: Bank not found
                      details:
                        type: object
                        properties:
                          hint:
                            type: string
                            const: >-
                              The bank identifier could not be found in the
                              database. You may need to import bank data first.
                        required:
                          - hint
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: identification_failed
                      message:
                        type: string
                        const: Failed to identify bank
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/identify/bank:
    post:
      operationId: bank.v1.identify.bank
      summary: Get bank record from IBAN or BBAN
      tags:
        - BankIdentificationV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyBankV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BankGetBankV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bank_not_found
                      message:
                        type: string
                        const: Bank not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bank_lookup_failed
                      message:
                        type: string
                        const: Failed to get bank information
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/identify/bic:
    post:
      operationId: bank.v1.identify.bic
      summary: Get BIC code from IBAN or BBAN
      tags:
        - BankIdentificationV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyBankV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      bic:
                        type:
                          - string
                          - 'null'
                    required:
                      - bic
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bic_not_found
                      message:
                        type: string
                        const: BIC code not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bic_lookup_failed
                      message:
                        type: string
                        const: Failed to get BIC code
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1:
    get:
      operationId: bank.v1.index
      description: Accepts `perPage`.
      summary: List banks with optional filters
      tags:
        - BankLookupV1
      parameters:
        - name: country
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: bic
          in: query
          schema:
            type: string
            maxLength: 11
        - name: search
          in: query
          schema:
            type: string
            maxLength: 255
        - name: provider
          in: query
          schema:
            type: string
            maxLength: 100
        - name: active_only
          in: query
          schema:
            type: boolean
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BankV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve banks
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/stats:
    get:
      operationId: bank.v1.stats
      description: Optional ?country=XX filter.
      summary: Bank registry statistics
      tags:
        - BankLookupV1
      parameters:
        - name: country
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: bic
          in: query
          schema:
            type: string
            maxLength: 11
        - name: search
          in: query
          schema:
            type: string
            maxLength: 255
        - name: provider
          in: query
          schema:
            type: string
            maxLength: 100
        - name: active_only
          in: query
          schema:
            type: boolean
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BankStatsV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve bank statistics
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/by-bic/{bic}:
    get:
      operationId: bank.v1.by-bic
      description: Pass ?all_branches=true to return all branch identifiers for the BIC.
      summary: Get bank(s) by BIC code
      tags:
        - BankLookupV1
      parameters:
        - name: bic
          in: path
          required: true
          schema:
            type: string
        - name: country
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: bic
          in: query
          schema:
            type: string
            maxLength: 11
        - name: search
          in: query
          schema:
            type: string
            maxLength: 255
        - name: provider
          in: query
          schema:
            type: string
            maxLength: 100
        - name: active_only
          in: query
          schema:
            type: boolean
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: all_branches
          in: query
          schema:
            type: boolean
            default: false
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BankByBicV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: No banks found for BIC code
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve bank by BIC
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/{country}/{identifier}:
    get:
      operationId: bank.v1.show
      summary: Get a specific bank by country + identifier
      tags:
        - BankLookupV1
      parameters:
        - name: country
          in: path
          required: true
          schema:
            type: string
        - name: identifier
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BankShowV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Bank not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve bank
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/iban/construct:
    post:
      operationId: bank.v1.iban.construct
      summary: Construct IBAN from BBAN + country or BIC
      tags:
        - BankUtilityV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConstructIbanV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      iban:
                        type:
                          - string
                          - 'null'
                      valid:
                        type: boolean
                      parsed:
                        type:
                          - object
                          - 'null'
                        properties:
                          country:
                            type: string
                          check_digits:
                            type: string
                          bban:
                            type: string
                          bank_id:
                            type: string
                          account:
                            type:
                              - string
                              - 'null'
                        required:
                          - country
                          - check_digits
                          - bban
                          - bank_id
                          - account
                    required:
                      - iban
                      - valid
                      - parsed
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: construction_error
                      message:
                        type: string
                        const: Failed to construct IBAN
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/iban/parse:
    post:
      operationId: bank.v1.iban.parse
      description: 'Returns: country, check_digits, bban, bank_id, account.'
      summary: Parse IBAN into its structural components
      tags:
        - BankUtilityV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseIbanV1Request'
      responses:
        '200':
          description: Explicit camelCase mapping of the service's snake_case keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      country:
                        type: string
                      checkDigits:
                        type: string
                      bban:
                        type: string
                      bankId:
                        type: string
                      account:
                        type: string
                    required:
                      - country
                      - checkDigits
                      - bban
                      - bankId
                      - account
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: parse_error
                      message:
                        type: string
                        const: Failed to parse IBAN
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/iban/validate:
    post:
      operationId: bank.v1.iban.validate
      description: Returns {iban, valid} and optionally {parsed} when valid.
      summary: Validate IBAN format and check digits
      tags:
        - BankUtilityV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateIbanV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      iban:
                        type: string
                      valid:
                        type: boolean
                      parsed:
                        type:
                          - object
                          - 'null'
                        properties:
                          country:
                            type: string
                          checkDigits:
                            type: string
                          bban:
                            type: string
                          bankId:
                            type: string
                          account:
                            type: string
                        required:
                          - country
                          - checkDigits
                          - bban
                          - bankId
                          - account
                    required:
                      - iban
                      - valid
                      - parsed
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_error
                      message:
                        type: string
                        const: Failed to validate IBAN
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/bic/validate:
    post:
      operationId: bank.v1.bic.validate
      description: Returns {bic, valid} and optionally {country} when valid.
      summary: Validate BIC format
      tags:
        - BankUtilityV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateBicV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      bic:
                        type: string
                      valid:
                        type: boolean
                      country:
                        type:
                          - string
                          - 'null'
                    required:
                      - bic
                      - valid
                      - country
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_error
                      message:
                        type: string
                        const: Failed to validate BIC
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/bic/country:
    post:
      operationId: bank.v1.bic.country
      summary: Extract country from BIC
      tags:
        - BankUtilityV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CountryFromBicV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      bic:
                        type: string
                      country:
                        type:
                          - string
                          - 'null'
                    required:
                      - bic
                      - country
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: extraction_error
                      message:
                        type: string
                        const: Failed to extract country from BIC
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /bank/v1/supported-countries:
    get:
      operationId: bank.v1.supported-countries
      summary: List IBAN-extraction-supported countries
      tags:
        - BankUtilityV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      countries:
                        type: array
                        items: {}
                      count:
                        type: integer
                    required:
                      - countries
                      - count
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: service_error
                      message:
                        type: string
                        const: Failed to get supported countries
                      details:
                        type: object
                        properties:
                          message:
                            type: string
                        required:
                          - message
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /clients/v1:
    delete:
      operationId: clients.v1.bulk-destroy
      description: |-
        DELETE clients/v1?ids[]=uuid1&ids[]=uuid2

        Atomic: all deletions happen in a single transaction. If any item fails
        authorization or has active cases, the whole batch is rolled back.

        Returns 200 with the list of deleted IDs on success.
      summary: Bulk soft-delete clients by ID
      tags:
        - Client
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: array
                        items:
                          type: string
                    required:
                      - deleted
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_failed
                      message:
                        type: string
                        const: The ids field is required.
                      details:
                        type: object
                        properties:
                          ids:
                            type: array
                            prefixItems:
                              - type: string
                                const: At least one ID is required.
                            minItems: 1
                            maxItems: 1
                            additionalItems: false
                        required:
                          - ids
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    get:
      operationId: clients.v1.index
      description: |-
        Two-tier authorization:
          1. Tenant-scope `clients.list` capability gates access to the endpoint.
          2. Layer-1 visibility filter restricts the returned set to clients
             that have a visibility-scope assignment reachable from the current
             operating scope (X-Scope header).
      summary: List all clients visible to the authenticated user in the active scope
      tags:
        - Client
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClientListResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: clients.v1.store
      description: Returns 201 Created + Location header pointing to the new resource.
      summary: Create a new client anchored at the operating scope (X-Scope)
      tags:
        - Client
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreClientRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                      displayName:
                        type: string
                      countryCode:
                        type: string
                      registrationNumber:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Company fields — always declared; null when client is
                          a person
                      companySnapshot:
                        anyOf:
                          - type: object
                            properties:
                              registrationNumber:
                                type: string
                              countryCode:
                                type: string
                              country:
                                type:
                                  - string
                                  - 'null'
                              vatNumber:
                                type:
                                  - string
                                  - 'null'
                              name:
                                type: string
                              tradingName:
                                type:
                                  - string
                                  - 'null'
                              status:
                                type: string
                              statusCode:
                                type:
                                  - string
                                  - 'null'
                              legalForm:
                                type:
                                  - string
                                  - 'null'
                              legalFormCode:
                                type:
                                  - string
                                  - 'null'
                              registrationDate:
                                type: string
                              incorporationDate:
                                type: string
                              dissolutionDate:
                                type: string
                              address:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  street:
                                    type:
                                      - string
                                      - 'null'
                                  street2:
                                    type:
                                      - string
                                      - 'null'
                                  postalCode:
                                    type:
                                      - string
                                      - 'null'
                                  city:
                                    type:
                                      - string
                                      - 'null'
                                  region:
                                    type:
                                      - string
                                      - 'null'
                                  countryCode:
                                    type:
                                      - string
                                      - 'null'
                                  country:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - street
                                  - street2
                                  - postalCode
                                  - city
                                  - region
                                  - countryCode
                                  - country
                              postalAddress:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  street:
                                    type:
                                      - string
                                      - 'null'
                                  street2:
                                    type:
                                      - string
                                      - 'null'
                                  postalCode:
                                    type:
                                      - string
                                      - 'null'
                                  city:
                                    type:
                                      - string
                                      - 'null'
                                  region:
                                    type:
                                      - string
                                      - 'null'
                                  countryCode:
                                    type:
                                      - string
                                      - 'null'
                                  country:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - street
                                  - street2
                                  - postalCode
                                  - city
                                  - region
                                  - countryCode
                                  - country
                              industryCode:
                                type:
                                  - string
                                  - 'null'
                              industryDescription:
                                type:
                                  - string
                                  - 'null'
                              naceCode:
                                type:
                                  - string
                                  - 'null'
                              numberOfEmployees:
                                type:
                                  - integer
                                  - 'null'
                              website:
                                type:
                                  - string
                                  - 'null'
                              email:
                                type:
                                  - string
                                  - 'null'
                              shareCapital:
                                type:
                                  - number
                                  - 'null'
                              capitalCurrency:
                                type:
                                  - string
                                  - 'null'
                              businessDescription:
                                type:
                                  - string
                                  - 'null'
                              sectorCode:
                                type:
                                  - string
                                  - 'null'
                              sectorDescription:
                                type:
                                  - string
                                  - 'null'
                              isGroupMember:
                                type:
                                  - boolean
                                  - 'null'
                              registrySource:
                                type: string
                              fetchedAt:
                                type: string
                              sourceUpdatedAt:
                                type: string
                              contacts:
                                type: array
                                description: >-
                                  rawData and rawResponseMeta are intentionally
                                  excluded.

                                  contacts included: type+value only (no rawData
                                  from sub-DTO).
                                items: {}
                              schemaVersion:
                                type: integer
                            required:
                              - registrationNumber
                              - countryCode
                              - country
                              - vatNumber
                              - name
                              - tradingName
                              - status
                              - statusCode
                              - legalForm
                              - legalFormCode
                              - registrationDate
                              - incorporationDate
                              - dissolutionDate
                              - address
                              - postalAddress
                              - industryCode
                              - industryDescription
                              - naceCode
                              - numberOfEmployees
                              - website
                              - email
                              - shareCapital
                              - capitalCurrency
                              - businessDescription
                              - sectorCode
                              - sectorDescription
                              - isGroupMember
                              - registrySource
                              - fetchedAt
                              - sourceUpdatedAt
                              - contacts
                              - schemaVersion
                          - type: 'null'
                          - type: object
                            properties:
                              industryCode:
                                type:
                                  - string
                                  - 'null'
                              industryDescription:
                                type:
                                  - string
                                  - 'null'
                            required:
                              - industryCode
                              - industryDescription
                      nationalIdLast4:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Person fields — always declared; null when client is a
                          company.

                          national_id intentionally omitted (full value requires
                          a dedicated endpoint + audit log).
                      dateOfBirth:
                        type:
                          - string
                          - 'null'
                      personSnapshot:
                        type:
                          - object
                          - 'null'
                        properties:
                          name:
                            type: string
                          countryCode:
                            type: string
                          nationalIdLast4:
                            type:
                              - string
                              - 'null'
                          dateOfBirth:
                            type:
                              - string
                              - 'null'
                          address:
                            type:
                              - string
                              - 'null'
                        required:
                          - name
                          - countryCode
                          - nationalIdLast4
                          - dateOfBirth
                          - address
                      status:
                        type: string
                        description: Status
                      onboardedAt:
                        type: string
                      riskClassification:
                        type:
                          - string
                          - 'null'
                        description: AML summary (read-only, set by compliance systems)
                      cddLevel:
                        type:
                          - string
                          - 'null'
                      pepStatus:
                        type: string
                      sanctionsStatus:
                        type: string
                      amlLastReviewedAt:
                        type:
                          - string
                          - 'null'
                      amlNextReviewDueAt:
                        type:
                          - string
                          - 'null'
                      conflictCheckStatus:
                        type: string
                        description: Conflict check
                      conflictCheckedAt:
                        type:
                          - string
                          - 'null'
                      conflictCheckNotes:
                        type:
                          - string
                          - 'null'
                      engagementType:
                        type:
                          - string
                          - 'null'
                        description: Engagement
                      taxResidenceCountryCode:
                        type:
                          - string
                          - 'null'
                        description: Tax / financial
                      vatNumber:
                        type:
                          - string
                          - 'null'
                      lei:
                        type:
                          - string
                          - 'null'
                      preferredLanguage:
                        type:
                          - string
                          - 'null'
                        description: Comms
                      notes:
                        type:
                          - string
                          - 'null'
                        description: Freeform
                      tags:
                        type:
                          - array
                          - 'null'
                        items: {}
                      lastSyncedAt:
                        type:
                          - string
                          - 'null'
                        description: Meta
                      createdBy:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      registryId:
                        type:
                          - integer
                          - 'null'
                        description: Entity chain registry ID
                    required:
                      - id
                      - type
                      - displayName
                      - countryCode
                      - registrationNumber
                      - companySnapshot
                      - nationalIdLast4
                      - dateOfBirth
                      - personSnapshot
                      - status
                      - onboardedAt
                      - riskClassification
                      - cddLevel
                      - pepStatus
                      - sanctionsStatus
                      - amlLastReviewedAt
                      - amlNextReviewDueAt
                      - conflictCheckStatus
                      - conflictCheckedAt
                      - conflictCheckNotes
                      - engagementType
                      - taxResidenceCountryCode
                      - vatNumber
                      - lei
                      - preferredLanguage
                      - notes
                      - tags
                      - lastSyncedAt
                      - createdBy
                      - createdAt
                      - updatedAt
                      - registryId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /clients/v1/{client}:
    get:
      operationId: clients.v1.show
      description: |-
        Two-layer check:
          1. Layer 1 visibility — client must be visible in the current scope.
             404 on miss to avoid leaking existence.
          2. Layer 3 permission — caller must hold a client role granting
             client.view (responsible_partner, client_team, client_viewer).
      summary: Show a single client
      tags:
        - Client
      parameters:
        - name: client
          in: path
          required: true
          description: The client ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                      displayName:
                        type: string
                      countryCode:
                        type: string
                      registrationNumber:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Company fields — always declared; null when client is
                          a person
                      companySnapshot:
                        anyOf:
                          - type: object
                            properties:
                              registrationNumber:
                                type: string
                              countryCode:
                                type: string
                              country:
                                type:
                                  - string
                                  - 'null'
                              vatNumber:
                                type:
                                  - string
                                  - 'null'
                              name:
                                type: string
                              tradingName:
                                type:
                                  - string
                                  - 'null'
                              status:
                                type: string
                              statusCode:
                                type:
                                  - string
                                  - 'null'
                              legalForm:
                                type:
                                  - string
                                  - 'null'
                              legalFormCode:
                                type:
                                  - string
                                  - 'null'
                              registrationDate:
                                type: string
                              incorporationDate:
                                type: string
                              dissolutionDate:
                                type: string
                              address:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  street:
                                    type:
                                      - string
                                      - 'null'
                                  street2:
                                    type:
                                      - string
                                      - 'null'
                                  postalCode:
                                    type:
                                      - string
                                      - 'null'
                                  city:
                                    type:
                                      - string
                                      - 'null'
                                  region:
                                    type:
                                      - string
                                      - 'null'
                                  countryCode:
                                    type:
                                      - string
                                      - 'null'
                                  country:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - street
                                  - street2
                                  - postalCode
                                  - city
                                  - region
                                  - countryCode
                                  - country
                              postalAddress:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  street:
                                    type:
                                      - string
                                      - 'null'
                                  street2:
                                    type:
                                      - string
                                      - 'null'
                                  postalCode:
                                    type:
                                      - string
                                      - 'null'
                                  city:
                                    type:
                                      - string
                                      - 'null'
                                  region:
                                    type:
                                      - string
                                      - 'null'
                                  countryCode:
                                    type:
                                      - string
                                      - 'null'
                                  country:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - street
                                  - street2
                                  - postalCode
                                  - city
                                  - region
                                  - countryCode
                                  - country
                              industryCode:
                                type:
                                  - string
                                  - 'null'
                              industryDescription:
                                type:
                                  - string
                                  - 'null'
                              naceCode:
                                type:
                                  - string
                                  - 'null'
                              numberOfEmployees:
                                type:
                                  - integer
                                  - 'null'
                              website:
                                type:
                                  - string
                                  - 'null'
                              email:
                                type:
                                  - string
                                  - 'null'
                              shareCapital:
                                type:
                                  - number
                                  - 'null'
                              capitalCurrency:
                                type:
                                  - string
                                  - 'null'
                              businessDescription:
                                type:
                                  - string
                                  - 'null'
                              sectorCode:
                                type:
                                  - string
                                  - 'null'
                              sectorDescription:
                                type:
                                  - string
                                  - 'null'
                              isGroupMember:
                                type:
                                  - boolean
                                  - 'null'
                              registrySource:
                                type: string
                              fetchedAt:
                                type: string
                              sourceUpdatedAt:
                                type: string
                              contacts:
                                type: array
                                description: >-
                                  rawData and rawResponseMeta are intentionally
                                  excluded.

                                  contacts included: type+value only (no rawData
                                  from sub-DTO).
                                items: {}
                              schemaVersion:
                                type: integer
                            required:
                              - registrationNumber
                              - countryCode
                              - country
                              - vatNumber
                              - name
                              - tradingName
                              - status
                              - statusCode
                              - legalForm
                              - legalFormCode
                              - registrationDate
                              - incorporationDate
                              - dissolutionDate
                              - address
                              - postalAddress
                              - industryCode
                              - industryDescription
                              - naceCode
                              - numberOfEmployees
                              - website
                              - email
                              - shareCapital
                              - capitalCurrency
                              - businessDescription
                              - sectorCode
                              - sectorDescription
                              - isGroupMember
                              - registrySource
                              - fetchedAt
                              - sourceUpdatedAt
                              - contacts
                              - schemaVersion
                          - type: 'null'
                          - type: object
                            properties:
                              industryCode:
                                type:
                                  - string
                                  - 'null'
                              industryDescription:
                                type:
                                  - string
                                  - 'null'
                            required:
                              - industryCode
                              - industryDescription
                      nationalIdLast4:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Person fields — always declared; null when client is a
                          company.

                          national_id intentionally omitted (full value requires
                          a dedicated endpoint + audit log).
                      dateOfBirth:
                        type:
                          - string
                          - 'null'
                      personSnapshot:
                        type:
                          - object
                          - 'null'
                        properties:
                          name:
                            type: string
                          countryCode:
                            type: string
                          nationalIdLast4:
                            type:
                              - string
                              - 'null'
                          dateOfBirth:
                            type:
                              - string
                              - 'null'
                          address:
                            type:
                              - string
                              - 'null'
                        required:
                          - name
                          - countryCode
                          - nationalIdLast4
                          - dateOfBirth
                          - address
                      status:
                        type: string
                        description: Status
                      onboardedAt:
                        type: string
                      riskClassification:
                        type:
                          - string
                          - 'null'
                        description: AML summary (read-only, set by compliance systems)
                      cddLevel:
                        type:
                          - string
                          - 'null'
                      pepStatus:
                        type: string
                      sanctionsStatus:
                        type: string
                      amlLastReviewedAt:
                        type:
                          - string
                          - 'null'
                      amlNextReviewDueAt:
                        type:
                          - string
                          - 'null'
                      conflictCheckStatus:
                        type: string
                        description: Conflict check
                      conflictCheckedAt:
                        type:
                          - string
                          - 'null'
                      conflictCheckNotes:
                        type:
                          - string
                          - 'null'
                      engagementType:
                        type:
                          - string
                          - 'null'
                        description: Engagement
                      taxResidenceCountryCode:
                        type:
                          - string
                          - 'null'
                        description: Tax / financial
                      vatNumber:
                        type:
                          - string
                          - 'null'
                      lei:
                        type:
                          - string
                          - 'null'
                      preferredLanguage:
                        type:
                          - string
                          - 'null'
                        description: Comms
                      notes:
                        type:
                          - string
                          - 'null'
                        description: Freeform
                      tags:
                        type:
                          - array
                          - 'null'
                        items: {}
                      lastSyncedAt:
                        type:
                          - string
                          - 'null'
                        description: Meta
                      createdBy:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      registryId:
                        type:
                          - integer
                          - 'null'
                        description: Entity chain registry ID
                    required:
                      - id
                      - type
                      - displayName
                      - countryCode
                      - registrationNumber
                      - companySnapshot
                      - nationalIdLast4
                      - dateOfBirth
                      - personSnapshot
                      - status
                      - onboardedAt
                      - riskClassification
                      - cddLevel
                      - pepStatus
                      - sanctionsStatus
                      - amlLastReviewedAt
                      - amlNextReviewDueAt
                      - conflictCheckStatus
                      - conflictCheckedAt
                      - conflictCheckNotes
                      - engagementType
                      - taxResidenceCountryCode
                      - vatNumber
                      - lei
                      - preferredLanguage
                      - notes
                      - tags
                      - lastSyncedAt
                      - createdBy
                      - createdAt
                      - updatedAt
                      - registryId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: clients.v1.update
      description: >-
        Supports both PUT (full replace) and PATCH (partial update).

        PATCH is the default — `UpdateClientRequest` uses `sometimes`
        throughout.
      summary: Update an existing client
      tags:
        - Client
      parameters:
        - name: client
          in: path
          required: true
          description: The client ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClientRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                      displayName:
                        type: string
                      countryCode:
                        type: string
                      registrationNumber:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Company fields — always declared; null when client is
                          a person
                      companySnapshot:
                        anyOf:
                          - type: object
                            properties:
                              registrationNumber:
                                type: string
                              countryCode:
                                type: string
                              country:
                                type:
                                  - string
                                  - 'null'
                              vatNumber:
                                type:
                                  - string
                                  - 'null'
                              name:
                                type: string
                              tradingName:
                                type:
                                  - string
                                  - 'null'
                              status:
                                type: string
                              statusCode:
                                type:
                                  - string
                                  - 'null'
                              legalForm:
                                type:
                                  - string
                                  - 'null'
                              legalFormCode:
                                type:
                                  - string
                                  - 'null'
                              registrationDate:
                                type: string
                              incorporationDate:
                                type: string
                              dissolutionDate:
                                type: string
                              address:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  street:
                                    type:
                                      - string
                                      - 'null'
                                  street2:
                                    type:
                                      - string
                                      - 'null'
                                  postalCode:
                                    type:
                                      - string
                                      - 'null'
                                  city:
                                    type:
                                      - string
                                      - 'null'
                                  region:
                                    type:
                                      - string
                                      - 'null'
                                  countryCode:
                                    type:
                                      - string
                                      - 'null'
                                  country:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - street
                                  - street2
                                  - postalCode
                                  - city
                                  - region
                                  - countryCode
                                  - country
                              postalAddress:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  street:
                                    type:
                                      - string
                                      - 'null'
                                  street2:
                                    type:
                                      - string
                                      - 'null'
                                  postalCode:
                                    type:
                                      - string
                                      - 'null'
                                  city:
                                    type:
                                      - string
                                      - 'null'
                                  region:
                                    type:
                                      - string
                                      - 'null'
                                  countryCode:
                                    type:
                                      - string
                                      - 'null'
                                  country:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - street
                                  - street2
                                  - postalCode
                                  - city
                                  - region
                                  - countryCode
                                  - country
                              industryCode:
                                type:
                                  - string
                                  - 'null'
                              industryDescription:
                                type:
                                  - string
                                  - 'null'
                              naceCode:
                                type:
                                  - string
                                  - 'null'
                              numberOfEmployees:
                                type:
                                  - integer
                                  - 'null'
                              website:
                                type:
                                  - string
                                  - 'null'
                              email:
                                type:
                                  - string
                                  - 'null'
                              shareCapital:
                                type:
                                  - number
                                  - 'null'
                              capitalCurrency:
                                type:
                                  - string
                                  - 'null'
                              businessDescription:
                                type:
                                  - string
                                  - 'null'
                              sectorCode:
                                type:
                                  - string
                                  - 'null'
                              sectorDescription:
                                type:
                                  - string
                                  - 'null'
                              isGroupMember:
                                type:
                                  - boolean
                                  - 'null'
                              registrySource:
                                type: string
                              fetchedAt:
                                type: string
                              sourceUpdatedAt:
                                type: string
                              contacts:
                                type: array
                                description: >-
                                  rawData and rawResponseMeta are intentionally
                                  excluded.

                                  contacts included: type+value only (no rawData
                                  from sub-DTO).
                                items: {}
                              schemaVersion:
                                type: integer
                            required:
                              - registrationNumber
                              - countryCode
                              - country
                              - vatNumber
                              - name
                              - tradingName
                              - status
                              - statusCode
                              - legalForm
                              - legalFormCode
                              - registrationDate
                              - incorporationDate
                              - dissolutionDate
                              - address
                              - postalAddress
                              - industryCode
                              - industryDescription
                              - naceCode
                              - numberOfEmployees
                              - website
                              - email
                              - shareCapital
                              - capitalCurrency
                              - businessDescription
                              - sectorCode
                              - sectorDescription
                              - isGroupMember
                              - registrySource
                              - fetchedAt
                              - sourceUpdatedAt
                              - contacts
                              - schemaVersion
                          - type: 'null'
                          - type: object
                            properties:
                              industryCode:
                                type:
                                  - string
                                  - 'null'
                              industryDescription:
                                type:
                                  - string
                                  - 'null'
                            required:
                              - industryCode
                              - industryDescription
                      nationalIdLast4:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Person fields — always declared; null when client is a
                          company.

                          national_id intentionally omitted (full value requires
                          a dedicated endpoint + audit log).
                      dateOfBirth:
                        type:
                          - string
                          - 'null'
                      personSnapshot:
                        type:
                          - object
                          - 'null'
                        properties:
                          name:
                            type: string
                          countryCode:
                            type: string
                          nationalIdLast4:
                            type:
                              - string
                              - 'null'
                          dateOfBirth:
                            type:
                              - string
                              - 'null'
                          address:
                            type:
                              - string
                              - 'null'
                        required:
                          - name
                          - countryCode
                          - nationalIdLast4
                          - dateOfBirth
                          - address
                      status:
                        type: string
                        description: Status
                      onboardedAt:
                        type: string
                      riskClassification:
                        type:
                          - string
                          - 'null'
                        description: AML summary (read-only, set by compliance systems)
                      cddLevel:
                        type:
                          - string
                          - 'null'
                      pepStatus:
                        type: string
                      sanctionsStatus:
                        type: string
                      amlLastReviewedAt:
                        type:
                          - string
                          - 'null'
                      amlNextReviewDueAt:
                        type:
                          - string
                          - 'null'
                      conflictCheckStatus:
                        type: string
                        description: Conflict check
                      conflictCheckedAt:
                        type:
                          - string
                          - 'null'
                      conflictCheckNotes:
                        type:
                          - string
                          - 'null'
                      engagementType:
                        type:
                          - string
                          - 'null'
                        description: Engagement
                      taxResidenceCountryCode:
                        type:
                          - string
                          - 'null'
                        description: Tax / financial
                      vatNumber:
                        type:
                          - string
                          - 'null'
                      lei:
                        type:
                          - string
                          - 'null'
                      preferredLanguage:
                        type:
                          - string
                          - 'null'
                        description: Comms
                      notes:
                        type:
                          - string
                          - 'null'
                        description: Freeform
                      tags:
                        type:
                          - array
                          - 'null'
                        items: {}
                      lastSyncedAt:
                        type:
                          - string
                          - 'null'
                        description: Meta
                      createdBy:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      registryId:
                        type:
                          - integer
                          - 'null'
                        description: Entity chain registry ID
                    required:
                      - id
                      - type
                      - displayName
                      - countryCode
                      - registrationNumber
                      - companySnapshot
                      - nationalIdLast4
                      - dateOfBirth
                      - personSnapshot
                      - status
                      - onboardedAt
                      - riskClassification
                      - cddLevel
                      - pepStatus
                      - sanctionsStatus
                      - amlLastReviewedAt
                      - amlNextReviewDueAt
                      - conflictCheckStatus
                      - conflictCheckedAt
                      - conflictCheckNotes
                      - engagementType
                      - taxResidenceCountryCode
                      - vatNumber
                      - lei
                      - preferredLanguage
                      - notes
                      - tags
                      - lastSyncedAt
                      - createdBy
                      - createdAt
                      - updatedAt
                      - registryId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: clients.v1.patch
      description: >-
        Supports both PUT (full replace) and PATCH (partial update).

        PATCH is the default — `UpdateClientRequest` uses `sometimes`
        throughout.
      summary: Update an existing client
      tags:
        - Client
      parameters:
        - name: client
          in: path
          required: true
          description: The client ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClientRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                      displayName:
                        type: string
                      countryCode:
                        type: string
                      registrationNumber:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Company fields — always declared; null when client is
                          a person
                      companySnapshot:
                        anyOf:
                          - type: object
                            properties:
                              registrationNumber:
                                type: string
                              countryCode:
                                type: string
                              country:
                                type:
                                  - string
                                  - 'null'
                              vatNumber:
                                type:
                                  - string
                                  - 'null'
                              name:
                                type: string
                              tradingName:
                                type:
                                  - string
                                  - 'null'
                              status:
                                type: string
                              statusCode:
                                type:
                                  - string
                                  - 'null'
                              legalForm:
                                type:
                                  - string
                                  - 'null'
                              legalFormCode:
                                type:
                                  - string
                                  - 'null'
                              registrationDate:
                                type: string
                              incorporationDate:
                                type: string
                              dissolutionDate:
                                type: string
                              address:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  street:
                                    type:
                                      - string
                                      - 'null'
                                  street2:
                                    type:
                                      - string
                                      - 'null'
                                  postalCode:
                                    type:
                                      - string
                                      - 'null'
                                  city:
                                    type:
                                      - string
                                      - 'null'
                                  region:
                                    type:
                                      - string
                                      - 'null'
                                  countryCode:
                                    type:
                                      - string
                                      - 'null'
                                  country:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - street
                                  - street2
                                  - postalCode
                                  - city
                                  - region
                                  - countryCode
                                  - country
                              postalAddress:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  street:
                                    type:
                                      - string
                                      - 'null'
                                  street2:
                                    type:
                                      - string
                                      - 'null'
                                  postalCode:
                                    type:
                                      - string
                                      - 'null'
                                  city:
                                    type:
                                      - string
                                      - 'null'
                                  region:
                                    type:
                                      - string
                                      - 'null'
                                  countryCode:
                                    type:
                                      - string
                                      - 'null'
                                  country:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - street
                                  - street2
                                  - postalCode
                                  - city
                                  - region
                                  - countryCode
                                  - country
                              industryCode:
                                type:
                                  - string
                                  - 'null'
                              industryDescription:
                                type:
                                  - string
                                  - 'null'
                              naceCode:
                                type:
                                  - string
                                  - 'null'
                              numberOfEmployees:
                                type:
                                  - integer
                                  - 'null'
                              website:
                                type:
                                  - string
                                  - 'null'
                              email:
                                type:
                                  - string
                                  - 'null'
                              shareCapital:
                                type:
                                  - number
                                  - 'null'
                              capitalCurrency:
                                type:
                                  - string
                                  - 'null'
                              businessDescription:
                                type:
                                  - string
                                  - 'null'
                              sectorCode:
                                type:
                                  - string
                                  - 'null'
                              sectorDescription:
                                type:
                                  - string
                                  - 'null'
                              isGroupMember:
                                type:
                                  - boolean
                                  - 'null'
                              registrySource:
                                type: string
                              fetchedAt:
                                type: string
                              sourceUpdatedAt:
                                type: string
                              contacts:
                                type: array
                                description: >-
                                  rawData and rawResponseMeta are intentionally
                                  excluded.

                                  contacts included: type+value only (no rawData
                                  from sub-DTO).
                                items: {}
                              schemaVersion:
                                type: integer
                            required:
                              - registrationNumber
                              - countryCode
                              - country
                              - vatNumber
                              - name
                              - tradingName
                              - status
                              - statusCode
                              - legalForm
                              - legalFormCode
                              - registrationDate
                              - incorporationDate
                              - dissolutionDate
                              - address
                              - postalAddress
                              - industryCode
                              - industryDescription
                              - naceCode
                              - numberOfEmployees
                              - website
                              - email
                              - shareCapital
                              - capitalCurrency
                              - businessDescription
                              - sectorCode
                              - sectorDescription
                              - isGroupMember
                              - registrySource
                              - fetchedAt
                              - sourceUpdatedAt
                              - contacts
                              - schemaVersion
                          - type: 'null'
                          - type: object
                            properties:
                              industryCode:
                                type:
                                  - string
                                  - 'null'
                              industryDescription:
                                type:
                                  - string
                                  - 'null'
                            required:
                              - industryCode
                              - industryDescription
                      nationalIdLast4:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Person fields — always declared; null when client is a
                          company.

                          national_id intentionally omitted (full value requires
                          a dedicated endpoint + audit log).
                      dateOfBirth:
                        type:
                          - string
                          - 'null'
                      personSnapshot:
                        type:
                          - object
                          - 'null'
                        properties:
                          name:
                            type: string
                          countryCode:
                            type: string
                          nationalIdLast4:
                            type:
                              - string
                              - 'null'
                          dateOfBirth:
                            type:
                              - string
                              - 'null'
                          address:
                            type:
                              - string
                              - 'null'
                        required:
                          - name
                          - countryCode
                          - nationalIdLast4
                          - dateOfBirth
                          - address
                      status:
                        type: string
                        description: Status
                      onboardedAt:
                        type: string
                      riskClassification:
                        type:
                          - string
                          - 'null'
                        description: AML summary (read-only, set by compliance systems)
                      cddLevel:
                        type:
                          - string
                          - 'null'
                      pepStatus:
                        type: string
                      sanctionsStatus:
                        type: string
                      amlLastReviewedAt:
                        type:
                          - string
                          - 'null'
                      amlNextReviewDueAt:
                        type:
                          - string
                          - 'null'
                      conflictCheckStatus:
                        type: string
                        description: Conflict check
                      conflictCheckedAt:
                        type:
                          - string
                          - 'null'
                      conflictCheckNotes:
                        type:
                          - string
                          - 'null'
                      engagementType:
                        type:
                          - string
                          - 'null'
                        description: Engagement
                      taxResidenceCountryCode:
                        type:
                          - string
                          - 'null'
                        description: Tax / financial
                      vatNumber:
                        type:
                          - string
                          - 'null'
                      lei:
                        type:
                          - string
                          - 'null'
                      preferredLanguage:
                        type:
                          - string
                          - 'null'
                        description: Comms
                      notes:
                        type:
                          - string
                          - 'null'
                        description: Freeform
                      tags:
                        type:
                          - array
                          - 'null'
                        items: {}
                      lastSyncedAt:
                        type:
                          - string
                          - 'null'
                        description: Meta
                      createdBy:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      registryId:
                        type:
                          - integer
                          - 'null'
                        description: Entity chain registry ID
                    required:
                      - id
                      - type
                      - displayName
                      - countryCode
                      - registrationNumber
                      - companySnapshot
                      - nationalIdLast4
                      - dateOfBirth
                      - personSnapshot
                      - status
                      - onboardedAt
                      - riskClassification
                      - cddLevel
                      - pepStatus
                      - sanctionsStatus
                      - amlLastReviewedAt
                      - amlNextReviewDueAt
                      - conflictCheckStatus
                      - conflictCheckedAt
                      - conflictCheckNotes
                      - engagementType
                      - taxResidenceCountryCode
                      - vatNumber
                      - lei
                      - preferredLanguage
                      - notes
                      - tags
                      - lastSyncedAt
                      - createdBy
                      - createdAt
                      - updatedAt
                      - registryId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: clients.v1.destroy
      description: |-
        Returns 204 No Content on success.
        Refuses deletion if active LegalCases exist.
      summary: Soft-delete a single client
      tags:
        - Client
      parameters:
        - name: client
          in: path
          required: true
          description: The client ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: active_cases
                      message:
                        type: string
                        const: >-
                          Cannot delete a client with active cases. Close or
                          archive all cases first.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /company/v1/capabilities:
    get:
      operationId: company.v1.capabilities
      description: 'Returns ETag + Cache-Control: private (slow-changing reference data).'
      summary: Get the authenticated user's general company data capabilities.
      tags:
        - CompanyIntelligenceV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      accessibleSubsets:
                        type:
                          - string
                          - 'null'
                      accessLevel:
                        type:
                          - string
                          - 'null'
                    required:
                      - accessibleSubsets
                      - accessLevel
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies:
    get:
      operationId: company.v1.companies.index
      summary: List companies accessible to the authenticated user.
      tags:
        - CompanyIntelligenceV1
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: sort
          in: query
          schema:
            type: string
        - name: filter[name]
          in: query
          schema:
            type: string
        - name: filter[countryCode]
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: filter[status]
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          page:
                            anyOf:
                              - type: string
                              - type: 'null'
                              - type: object
                          perPage:
                            anyOf:
                              - type: string
                              - type: 'null'
                              - type: object
                          total:
                            type: string
                          totalPages:
                            type: string
                        required:
                          - page
                          - perPage
                          - total
                          - totalPages
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /company/v1/companies/{id}:
    get:
      operationId: company.v1.companies.show
      description: >-
        Returns ETag + Cache-Control: private, max-age=300 for conditional-GET
        support.
      summary: Show a single company (basic info + optional profile).
      tags:
        - CompanyIntelligenceV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: profile
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      orgNo:
                        type:
                          - string
                          - 'null'
                      name:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      legalForm:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - orgNo
                      - name
                      - countryCode
                      - status
                      - legalForm
                      - source
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Company not found or access denied
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: invalid_profile
                          message:
                            type: string
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: unknown_profile
                          message:
                            type: string
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
    post:
      operationId: company.v1.companies.fetch-detailed
      summary: Detailed company fetch with profile/subset/priority options.
      tags:
        - CompanyIntelligenceV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchDetailedV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      orgNo:
                        type:
                          - string
                          - 'null'
                      name:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      legalForm:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - orgNo
                      - name
                      - countryCode
                      - status
                      - legalForm
                      - source
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Company not found or access denied
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /company/v1/companies/{id}/import:
    post:
      operationId: company.v1.companies.import
      description: Returns 201 + Location header on success.
      summary: Import / create company data from external sources.
      tags:
        - CompanyIntelligenceV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportCompanyV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      orgNo:
                        type:
                          - string
                          - 'null'
                      name:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      legalForm:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - orgNo
                      - name
                      - countryCode
                      - status
                      - legalForm
                      - source
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '429':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: rate_limit_exceeded
                      message:
                        type: string
                        const: Too many import requests
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /company/v1/companies/{id}/refetch:
    post:
      operationId: company.v1.companies.refetch
      description: >-
        Returns a conflict error if a refetch is already in progress for this
        company.
      summary: Re-fetch company data synchronously from upstream integrations.
      tags:
        - CompanyIntelligenceV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefetchCompanyV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      orgNo:
                        type:
                          - string
                          - 'null'
                      name:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      legalForm:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - orgNo
                      - name
                      - countryCode
                      - status
                      - legalForm
                      - source
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Company not found or access denied
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: conflict
                      message:
                        type: string
                        const: Refetch already in progress for this company
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /company/v1/companies/{id}/access:
    get:
      operationId: company.v1.companies.access
      summary: Get the authenticated user's access details for a specific company.
      tags:
        - CompanyIntelligenceV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      companyId:
                        type: string
                      accessibleSubsets:
                        type: array
                        items: {}
                      accessLevel:
                        type: string
                        enum:
                          - premium
                          - standard
                          - basic
                          - none
                    required:
                      - companyId
                      - accessibleSubsets
                      - accessLevel
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/jobs/active:
    get:
      operationId: company.v1.jobs.active
      summary: Get active (running) jobs.
      tags:
        - CompanyJobV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/jobs/queued:
    get:
      operationId: company.v1.jobs.queued
      summary: Get queued jobs.
      tags:
        - CompanyJobV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/jobs/status:
    get:
      operationId: company.v1.jobs.status
      summary: Get status overview counts.
      tags:
        - CompanyJobV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      queued:
                        type: integer
                        const: 3
                      running:
                        type: integer
                        const: 1
                      completed:
                        type: integer
                        const: 15
                      failed:
                        type: integer
                        const: 2
                      cancelled:
                        type: integer
                        const: 1
                      total:
                        type: integer
                        const: 22
                    required:
                      - queued
                      - running
                      - completed
                      - failed
                      - cancelled
                      - total
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/jobs/import:
    post:
      operationId: company.v1.jobs.import
      summary: Create a company import job.
      tags:
        - CompanyJobV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImportJobV1Request'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      type:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      progress:
                        type:
                          - string
                          - 'null'
                      totalItems:
                        type:
                          - string
                          - 'null'
                      userId:
                        type:
                          - string
                          - 'null'
                      parameters:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      estimatedDuration:
                        type:
                          - string
                          - 'null'
                      estimatedCompletion:
                        type:
                          - string
                          - 'null'
                      completedAt:
                        type:
                          - string
                          - 'null'
                      cancelledAt:
                        type:
                          - string
                          - 'null'
                      failedAt:
                        type:
                          - string
                          - 'null'
                      retriedFrom:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - type
                      - status
                      - progress
                      - totalItems
                      - userId
                      - parameters
                      - createdAt
                      - updatedAt
                      - estimatedDuration
                      - estimatedCompletion
                      - completedAt
                      - cancelledAt
                      - failedAt
                      - retriedFrom
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /company/v1/jobs/bulk-refresh:
    post:
      operationId: company.v1.jobs.bulk-refresh
      summary: Create a bulk refresh job.
      tags:
        - CompanyJobV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkRefreshJobV1Request'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      type:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      progress:
                        type:
                          - string
                          - 'null'
                      totalItems:
                        type:
                          - string
                          - 'null'
                      userId:
                        type:
                          - string
                          - 'null'
                      parameters:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      estimatedDuration:
                        type:
                          - string
                          - 'null'
                      estimatedCompletion:
                        type:
                          - string
                          - 'null'
                      completedAt:
                        type:
                          - string
                          - 'null'
                      cancelledAt:
                        type:
                          - string
                          - 'null'
                      failedAt:
                        type:
                          - string
                          - 'null'
                      retriedFrom:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - type
                      - status
                      - progress
                      - totalItems
                      - userId
                      - parameters
                      - createdAt
                      - updatedAt
                      - estimatedDuration
                      - estimatedCompletion
                      - completedAt
                      - cancelledAt
                      - failedAt
                      - retriedFrom
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /company/v1/jobs/{jobId}:
    get:
      operationId: company.v1.jobs.show
      summary: Show a specific job.
      tags:
        - CompanyJobV1
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      type:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      progress:
                        type:
                          - string
                          - 'null'
                      totalItems:
                        type:
                          - string
                          - 'null'
                      userId:
                        type:
                          - string
                          - 'null'
                      parameters:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      estimatedDuration:
                        type:
                          - string
                          - 'null'
                      estimatedCompletion:
                        type:
                          - string
                          - 'null'
                      completedAt:
                        type:
                          - string
                          - 'null'
                      cancelledAt:
                        type:
                          - string
                          - 'null'
                      failedAt:
                        type:
                          - string
                          - 'null'
                      retriedFrom:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - type
                      - status
                      - progress
                      - totalItems
                      - userId
                      - parameters
                      - createdAt
                      - updatedAt
                      - estimatedDuration
                      - estimatedCompletion
                      - completedAt
                      - cancelledAt
                      - failedAt
                      - retriedFrom
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Job not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    delete:
      operationId: company.v1.jobs.cancel
      summary: Cancel a job.
      tags:
        - CompanyJobV1
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      type:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      progress:
                        type:
                          - string
                          - 'null'
                      totalItems:
                        type:
                          - string
                          - 'null'
                      userId:
                        type:
                          - string
                          - 'null'
                      parameters:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      estimatedDuration:
                        type:
                          - string
                          - 'null'
                      estimatedCompletion:
                        type:
                          - string
                          - 'null'
                      completedAt:
                        type:
                          - string
                          - 'null'
                      cancelledAt:
                        type:
                          - string
                          - 'null'
                      failedAt:
                        type:
                          - string
                          - 'null'
                      retriedFrom:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - type
                      - status
                      - progress
                      - totalItems
                      - userId
                      - parameters
                      - createdAt
                      - updatedAt
                      - estimatedDuration
                      - estimatedCompletion
                      - completedAt
                      - cancelledAt
                      - failedAt
                      - retriedFrom
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Job not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: conflict
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /company/v1/jobs/{jobId}/retry:
    post:
      operationId: company.v1.jobs.retry
      summary: Retry a failed job.
      tags:
        - CompanyJobV1
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                      type:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      progress:
                        type:
                          - string
                          - 'null'
                      totalItems:
                        type:
                          - string
                          - 'null'
                      userId:
                        type:
                          - string
                          - 'null'
                      parameters:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      estimatedDuration:
                        type:
                          - string
                          - 'null'
                      estimatedCompletion:
                        type:
                          - string
                          - 'null'
                      completedAt:
                        type:
                          - string
                          - 'null'
                      cancelledAt:
                        type:
                          - string
                          - 'null'
                      failedAt:
                        type:
                          - string
                          - 'null'
                      retriedFrom:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - type
                      - status
                      - progress
                      - totalItems
                      - userId
                      - parameters
                      - createdAt
                      - updatedAt
                      - estimatedDuration
                      - estimatedCompletion
                      - completedAt
                      - cancelledAt
                      - failedAt
                      - retriedFrom
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Job not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: conflict
                      message:
                        type: string
                        const: Only failed jobs can be retried
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /company/v1/companies/{id}/report:
    get:
      operationId: company.v1.companies.report
      description: >-
        Generate a PDF report for a company based on its latest dataset
        information.


        Returns binary application/pdf — not the standard {data,meta} envelope.

        This endpoint does not support the Idempotency-Key header.


        Query parameters:
          - sections (string, optional): comma-separated section identifiers; defaults to 'all'
          - full     (bool-ish, optional): whether to include full extended data; defaults to false
          - filename (string, optional): override for the downloaded filename
      summary: Generate a PDF company report
      tags:
        - CompanyReportV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    const: Failed to generate company report
                required:
                  - message
  /company/v1/search:
    get:
      operationId: company.v1.search
      description: >-
        Uses cursor-based pagination. The cursor is an opaque token — clients
        should

        pass it back as received and must not attempt to decode or construct it.
      summary: Free-text company search — cursor paginated.
      tags:
        - CompanySearchV1
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 100
        - name: country
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: country_code
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          schema:
            type:
              - string
              - 'null'
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          perPage:
                            type:
                              - object
                              - 'null'
                          nextCursor:
                            type:
                              - string
                              - 'null'
                          prevCursor:
                            type:
                              - string
                              - 'null'
                        required:
                          - perPage
                          - nextCursor
                          - prevCursor
                      externalSearchEnabled:
                        type: boolean
                    required:
                      - requestId
                      - pagination
                      - externalSearchEnabled
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /company/v1/lookup:
    get:
      operationId: company.v1.lookup
      description: |-
        Accepts both `registrationNumber` (v1 canonical) and the deprecated
        `registration_number` alias, via LookupCompanyV1Request.

        Returns the internal company identifier as data.internalId (previously
        returned as a separate company_id field outside the envelope).
      summary: Direct registration-number lookup.
      tags:
        - CompanySearchV1
      parameters:
        - name: country
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: country_code
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: registrationNumber
          in: query
          schema:
            type: string
            maxLength: 64
        - name: registration_number
          in: query
          schema:
            type: string
            maxLength: 64
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      registrationNumber:
                        type:
                          - string
                          - 'null'
                      name:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      status:
                        type:
                          - string
                          - 'null'
                      legalForm:
                        type:
                          - string
                          - 'null'
                      address:
                        type:
                          - string
                          - 'null'
                      internalId:
                        type:
                          - string
                          - 'null'
                      registrySource:
                        type:
                          - string
                          - 'null'
                    required:
                      - registrationNumber
                      - name
                      - countryCode
                      - status
                      - legalForm
                      - address
                      - internalId
                      - registrySource
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: >-
                          No integration returned a match for the given
                          registration number.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /company/v1/companies/{id}/information:
    get:
      operationId: company.v1.companies.information
      summary: Return a company's core information
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/financials:
    get:
      operationId: company.v1.companies.financials
      summary: Return a company's financial figures
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/rating:
    get:
      operationId: company.v1.companies.rating
      summary: Return a company's credit rating
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/addresses:
    get:
      operationId: company.v1.companies.addresses
      summary: List a company's addresses
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/announcements:
    get:
      operationId: company.v1.companies.announcements
      summary: List a company's announcements
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/events:
    get:
      operationId: company.v1.companies.events
      summary: List a company's events
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/roles:
    get:
      operationId: company.v1.companies.roles
      summary: List a company's roles
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/signatories:
    get:
      operationId: company.v1.companies.signatories
      summary: List a company's signatories
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/shareholders:
    get:
      operationId: company.v1.companies.shareholders
      summary: List a company's shareholders
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/exceptions:
    get:
      operationId: company.v1.companies.exceptions
      summary: List a company's exceptions
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/activity-classifications:
    get:
      operationId: company.v1.companies.activity-classifications
      summary: List a company's activity classifications
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/group-structure:
    get:
      operationId: company.v1.companies.group-structure
      summary: Return a company's group structure
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /company/v1/companies/{id}/metric-snapshots:
    get:
      operationId: company.v1.companies.metric-snapshots
      summary: List a company's metric snapshots
      tags:
        - CompanySubsetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subsetType:
                        type:
                          - string
                          - 'null'
                      data:
                        type:
                          - string
                          - 'null'
                      resolvedAt:
                        type:
                          - string
                          - 'null'
                      source:
                        type:
                          - string
                          - 'null'
                    required:
                      - subsetType
                      - data
                      - resolvedAt
                      - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/consents/callback/{integration}:
    get:
      operationId: accounttracking.v1.consents.callback
      description: |-
        Process OAuth callback from bank provider.

        Returns the raw result from the callback registry — may be a JSON
        response or an HTTP 302 redirect depending on the integration's
        callback processor. Never wrapped in {data,meta}.
      summary: Process the bank OAuth callback
      tags:
        - ConsentCallbackV1
      parameters:
        - name: integration
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: >-
            Otherwise return a plain JSON payload (kept compatible with the
            previous response shape).
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                      data:
                        type: array
                        items: {}
                    required:
                      - success
                      - data
                  - type: array
                    items: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    const: Callback processing failed
                  error:
                    type: string
                required:
                  - success
                  - message
                  - error
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    const: An unexpected error occurred
                required:
                  - success
                  - message
  /accounttracking/v1/consents/statistics:
    get:
      operationId: accounttracking.v1.consents.statistics
      description: Consent statistics for the current user/scope.
      summary: Consent statistics for the current scope
      tags:
        - ConsentV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                      active:
                        type: integer
                      expired:
                        type: integer
                      revoked:
                        type: integer
                      expiring_soon:
                        type: integer
                      by_integration:
                        type: object
                        additionalProperties: {}
                    required:
                      - total
                      - active
                      - expired
                      - revoked
                      - expiring_soon
                      - by_integration
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/consents/revoke-expired:
    post:
      operationId: accounttracking.v1.consents.revoke-expired
      description: |-
        Batch-revoke expired consents. This endpoint does not support the
        Idempotency-Key header.
      summary: Batch-revoke expired consents
      tags:
        - ConsentV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      expiredCount:
                        type: integer
                      processedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - expiredCount
                      - processedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: revoke_expired_failed
                      message:
                        type: string
                        const: Failed to cleanup expired consents
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/consents/integration/{integration}:
    get:
      operationId: accounttracking.v1.consents.by-integration
      description: List consents by integration name.
      summary: List consents by integration
      tags:
        - ConsentV1
      parameters:
        - name: integration
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - createdAt
              - '-createdAt'
              - expiresAt
              - '-expiresAt'
        - name: filter[integration]
          in: query
          schema:
            type: string
        - name: filter[status]
          in: query
          schema:
            type: string
        - name: filter[trackedAccountId]
          in: query
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        integrationName:
                          type: string
                        purpose:
                          type: string
                        scope:
                          type: string
                        status:
                          type: string
                        isValid:
                          type: boolean
                        expiresAt:
                          type:
                            - string
                            - 'null'
                        grantedAt:
                          type:
                            - string
                            - 'null'
                        revokedAt:
                          type:
                            - string
                            - 'null'
                        remainingDays:
                          type: string
                        trackedAccountId:
                          type: string
                        ownerId:
                          type: string
                        ownerType:
                          type: string
                        metadata:
                          type: string
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - integrationName
                        - purpose
                        - scope
                        - status
                        - isValid
                        - expiresAt
                        - grantedAt
                        - revokedAt
                        - remainingDays
                        - trackedAccountId
                        - ownerId
                        - ownerType
                        - metadata
                        - createdAt
                        - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type: integer
                          currentPage:
                            type: integer
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/consents/integration/{integration}/active:
    get:
      operationId: accounttracking.v1.consents.by-integration.active
      description: List active consents by integration name.
      summary: List active consents by integration
      tags:
        - ConsentV1
      parameters:
        - name: integration
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - createdAt
              - '-createdAt'
              - expiresAt
              - '-expiresAt'
        - name: filter[integration]
          in: query
          schema:
            type: string
        - name: filter[status]
          in: query
          schema:
            type: string
        - name: filter[trackedAccountId]
          in: query
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        integrationName:
                          type: string
                        purpose:
                          type: string
                        scope:
                          type: string
                        status:
                          type: string
                        isValid:
                          type: boolean
                        expiresAt:
                          type:
                            - string
                            - 'null'
                        grantedAt:
                          type:
                            - string
                            - 'null'
                        revokedAt:
                          type:
                            - string
                            - 'null'
                        remainingDays:
                          type: string
                        trackedAccountId:
                          type: string
                        ownerId:
                          type: string
                        ownerType:
                          type: string
                        metadata:
                          type: string
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - integrationName
                        - purpose
                        - scope
                        - status
                        - isValid
                        - expiresAt
                        - grantedAt
                        - revokedAt
                        - remainingDays
                        - trackedAccountId
                        - ownerId
                        - ownerType
                        - metadata
                        - createdAt
                        - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type: integer
                          currentPage:
                            type: integer
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/consents:
    get:
      operationId: accounttracking.v1.consents.index
      description: |-
        List consents visible to actor in current context.
        Returns page-paginated ApiCollection.
      summary: List consents visible to the actor
      tags:
        - ConsentV1
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - createdAt
              - '-createdAt'
              - expiresAt
              - '-expiresAt'
        - name: filter[integration]
          in: query
          schema:
            type: string
        - name: filter[status]
          in: query
          schema:
            type: string
        - name: filter[trackedAccountId]
          in: query
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        integrationName:
                          type: string
                        purpose:
                          type: string
                        scope:
                          type: string
                        status:
                          type: string
                        isValid:
                          type: boolean
                        expiresAt:
                          type:
                            - string
                            - 'null'
                        grantedAt:
                          type:
                            - string
                            - 'null'
                        revokedAt:
                          type:
                            - string
                            - 'null'
                        remainingDays:
                          type: string
                        trackedAccountId:
                          type: string
                        ownerId:
                          type: string
                        ownerType:
                          type: string
                        metadata:
                          type: string
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - integrationName
                        - purpose
                        - scope
                        - status
                        - isValid
                        - expiresAt
                        - grantedAt
                        - revokedAt
                        - remainingDays
                        - trackedAccountId
                        - ownerId
                        - ownerType
                        - metadata
                        - createdAt
                        - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type: integer
                          currentPage:
                            type: integer
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
    post:
      operationId: accounttracking.v1.consents.store
      description: |-
        Create a new consent.
        Returns 201 + Location header.
      summary: Create a bank-access consent
      tags:
        - ConsentV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreConsentV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      integrationName:
                        type: string
                      purpose:
                        type: string
                      scope:
                        type: string
                      status:
                        type: string
                      isValid:
                        type: boolean
                      expiresAt:
                        type:
                          - string
                          - 'null'
                      grantedAt:
                        type:
                          - string
                          - 'null'
                      revokedAt:
                        type:
                          - string
                          - 'null'
                      remainingDays:
                        type: string
                      trackedAccountId:
                        type: string
                      ownerId:
                        type: string
                      ownerType:
                        type: string
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - integrationName
                      - purpose
                      - scope
                      - status
                      - isValid
                      - expiresAt
                      - grantedAt
                      - revokedAt
                      - remainingDays
                      - trackedAccountId
                      - ownerId
                      - ownerType
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: consent_creation_failed
                      message:
                        type: string
                        const: Failed to create consent
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/consents/{consent}:
    get:
      operationId: accounttracking.v1.consents.show
      description: Fetch a single consent.
      summary: Fetch a single consent
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      integrationName:
                        type: string
                      purpose:
                        type: string
                      scope:
                        type: string
                      status:
                        type: string
                      isValid:
                        type: boolean
                      expiresAt:
                        type:
                          - string
                          - 'null'
                      grantedAt:
                        type:
                          - string
                          - 'null'
                      revokedAt:
                        type:
                          - string
                          - 'null'
                      remainingDays:
                        type: string
                      trackedAccountId:
                        type: string
                      ownerId:
                        type: string
                      ownerType:
                        type: string
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - integrationName
                      - purpose
                      - scope
                      - status
                      - isValid
                      - expiresAt
                      - grantedAt
                      - revokedAt
                      - remainingDays
                      - trackedAccountId
                      - ownerId
                      - ownerType
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    patch:
      operationId: accounttracking.v1.consents.update
      description: Update consent metadata.
      summary: Update consent metadata
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConsentV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      integrationName:
                        type: string
                      purpose:
                        type: string
                      scope:
                        type: string
                      status:
                        type: string
                      isValid:
                        type: boolean
                      expiresAt:
                        type:
                          - string
                          - 'null'
                      grantedAt:
                        type:
                          - string
                          - 'null'
                      revokedAt:
                        type:
                          - string
                          - 'null'
                      remainingDays:
                        type: string
                      trackedAccountId:
                        type: string
                      ownerId:
                        type: string
                      ownerType:
                        type: string
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - integrationName
                      - purpose
                      - scope
                      - status
                      - isValid
                      - expiresAt
                      - grantedAt
                      - revokedAt
                      - remainingDays
                      - trackedAccountId
                      - ownerId
                      - ownerType
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: consent_update_failed
                      message:
                        type: string
                        const: Failed to update consent
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: accounttracking.v1.consents.destroy
      description: |-
        Soft-delete (revoke) a consent.
        Returns 204 No Content.
      summary: Revoke (soft-delete) a consent
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/consents/{consent}/status:
    get:
      operationId: accounttracking.v1.consents.status
      description: Return live consent status fields.
      summary: Return live consent status fields
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      consentId:
                        type: integer
                      status:
                        type: string
                      isValid:
                        type: boolean
                      expiresAt:
                        type: string
                      remainingDays:
                        type:
                          - integer
                          - 'null'
                      grantedAt:
                        type: string
                      revokedAt:
                        type: string
                    required:
                      - consentId
                      - status
                      - isValid
                      - expiresAt
                      - remainingDays
                      - grantedAt
                      - revokedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/consents/{consent}/validate:
    post:
      operationId: accounttracking.v1.consents.validate
      description: Validate consent for a specific operation.
      summary: Validate consent for an operation
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateConsentV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      consentId:
                        type: integer
                      operation: {}
                      isValid:
                        type: boolean
                      consentStatus:
                        type: string
                      validationTimestamp:
                        type:
                          - string
                          - 'null'
                    required:
                      - consentId
                      - operation
                      - isValid
                      - consentStatus
                      - validationTimestamp
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/consents/{consent}/remaining-days:
    get:
      operationId: accounttracking.v1.consents.remaining-days
      description: Return remaining validity days for a consent.
      summary: Return remaining validity days
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      consentId:
                        type: integer
                      remainingDays:
                        type:
                          - integer
                          - 'null'
                      expiresAt:
                        type: string
                      isExpired:
                        type: boolean
                    required:
                      - consentId
                      - remainingDays
                      - expiresAt
                      - isExpired
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/consents/{consent}/revoke:
    post:
      operationId: accounttracking.v1.consents.revoke
      description: |-
        Explicitly revoke a consent.
        Returns 204 No Content.
      summary: Explicitly revoke a consent
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: revoke_failed
                      message:
                        type: string
                        const: Failed to revoke consent
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/consents/{consent}/renew:
    post:
      operationId: accounttracking.v1.consents.renew
      description: |-
        Renew a consent by creating a new one and revoking the old.
        Returns 201 + new consent resource.
      summary: Renew a consent by replacing it
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      oldConsentId:
                        type: integer
                      newConsent:
                        type: object
                        properties:
                          id:
                            type: string
                          integrationName:
                            type: string
                          purpose:
                            type: string
                          scope:
                            type: string
                          status:
                            type: string
                          isValid:
                            type: boolean
                          expiresAt:
                            type:
                              - string
                              - 'null'
                          grantedAt:
                            type:
                              - string
                              - 'null'
                          revokedAt:
                            type:
                              - string
                              - 'null'
                          remainingDays:
                            type: string
                          trackedAccountId:
                            type: string
                          ownerId:
                            type: string
                          ownerType:
                            type: string
                          metadata:
                            type: string
                          createdAt:
                            type:
                              - string
                              - 'null'
                          updatedAt:
                            type:
                              - string
                              - 'null'
                        required:
                          - id
                          - integrationName
                          - purpose
                          - scope
                          - status
                          - isValid
                          - expiresAt
                          - grantedAt
                          - revokedAt
                          - remainingDays
                          - trackedAccountId
                          - ownerId
                          - ownerType
                          - metadata
                          - createdAt
                          - updatedAt
                      requiresRedirect:
                        type: boolean
                    required:
                      - oldConsentId
                      - newConsent
                      - requiresRedirect
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: renew_failed
                      message:
                        type: string
                        const: Failed to renew consent
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/consents/{consent}/initiate-redirect:
    post:
      operationId: accounttracking.v1.consents.initiate-redirect
      description: >-
        Initiate OAuth redirect for consent.


        Returns JSON {data:{consentId, redirectUrl, expiresIn}} — not an HTTP
        302.

        The client receives the URL and opens it.

        This endpoint does not support the Idempotency-Key header.
      summary: Initiate the OAuth consent redirect
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateRedirectV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      consentId:
                        type: integer
                      redirectUrl:
                        type: string
                      expiresIn:
                        type: integer
                        const: 300
                    required:
                      - consentId
                      - redirectUrl
                      - expiresIn
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: redirect_failed
                      message:
                        type: string
                        const: Failed to initiate redirect
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/consents/{consent}/visibility:
    get:
      operationId: accounttracking.v1.consents.visibility
      description: List visibility assignments for a consent.
      summary: List visibility assignments for a consent
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      consentId:
                        type: integer
                      visibilityAssignments:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            scopeType:
                              type: string
                            scopeId:
                              type: string
                            visibilityLevel:
                              type: string
                            assignmentType:
                              type: string
                            expiresAt:
                              type: string
                            grantedBy:
                              type:
                                - string
                                - 'null'
                            createdAt:
                              type: string
                          required:
                            - id
                            - scopeType
                            - scopeId
                            - visibilityLevel
                            - assignmentType
                            - expiresAt
                            - grantedBy
                            - createdAt
                    required:
                      - consentId
                      - visibilityAssignments
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: accounttracking.v1.consents.visibility.share
      description: |-
        Share consent with another scope.
        Returns 201.
      summary: Share a consent with another scope
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareConsentV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      consentId:
                        type: integer
                      scopeType: {}
                      scopeId: {}
                      visibilityLevel: {}
                    required:
                      - consentId
                      - scopeType
                      - scopeId
                      - visibilityLevel
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: share_failed
                      message:
                        type: string
                        const: Failed to share consent
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: accounttracking.v1.consents.visibility.revoke
      description: |-
        Revoke consent sharing from a scope.
        Returns 204 No Content.
      summary: Revoke consent sharing from a scope
      tags:
        - ConsentV1
      parameters:
        - name: consent
          in: path
          required: true
          description: The consent ID
          schema:
            type: integer
        - name: scopeType
          in: query
          required: true
          schema:
            type: string
            enum:
              - user
              - tenant
              - group
              - project
        - name: scopeId
          in: query
          required: true
          schema:
            type: string
            maxLength: 255
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: revoke_sharing_failed
                      message:
                        type: string
                        const: Failed to revoke sharing
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/accounts/{accountId}/counterparts:
    get:
      operationId: accounttracking.v1.accounts.counterparts
      description: >-
        Get counterparts for a specific account. Also accepts the deprecated
        flat query parameters.
      summary: List counterparts for a tracked account
      tags:
        - CounterpartV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: page
          in: query
          description: ── v1 standard pagination ────────────────────────────────────
          schema:
            type: integer
            minimum: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: per_page
          in: query
          description: Deprecated alias of perPage
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: sort
          in: query
          schema:
            type: string
        - name: filter[name]
          in: query
          schema:
            type: string
            maxLength: 255
        - name: filter[type]
          in: query
          schema:
            type: string
        - name: filter[parentId]
          in: query
          schema:
            type: integer
        - name: filter[accessScope]
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: counterpart_identifier
          in: query
          description: ── Deprecated flat filters — prefer filter[field]=value ────────────
          schema:
            type: string
            maxLength: 255
        - name: counterpart_type
          in: query
          schema:
            type: string
        - name: country_code
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: access_scope
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: creation_source
          in: query
          schema:
            type: string
            maxLength: 50
        - name: min_confidence
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: is_manual
          in: query
          schema:
            type: boolean
        - name: startDate
          in: query
          description: ── Timeframe (both camelCase and snake_case) ─────────────────
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: start_date
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: endDate
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: end_date
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: rootsOnly
          in: query
          description: ── Include flags (both camelCase and snake_case) ─────────────
          schema:
            type: boolean
        - name: roots_only
          in: query
          schema:
            type: boolean
        - name: includeParent
          in: query
          schema:
            type: boolean
        - name: include_parent
          in: query
          schema:
            type: boolean
        - name: includeChildren
          in: query
          schema:
            type: boolean
        - name: include_children
          in: query
          schema:
            type: boolean
        - name: includeRelationships
          in: query
          schema:
            type: boolean
        - name: include_relationships
          in: query
          schema:
            type: boolean
        - name: includeBoundEntities
          in: query
          schema:
            type: boolean
        - name: include_bound_entities
          in: query
          schema:
            type: boolean
        - name: groupByParent
          in: query
          schema:
            type: boolean
        - name: group_by_parent
          in: query
          schema:
            type: boolean
        - name: minConfidence
          in: query
          description: ── Min confidence (camelCase alias) ──────────────────────────
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: accessScope
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: creationSource
          in: query
          schema:
            type: string
            maxLength: 50
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            ── Core identity
                            ───────────────────────────────────────────────
                        counterpartIdentifier:
                          type: string
                        name:
                          type: string
                        nameLowercase:
                          type:
                            - string
                            - 'null'
                        type:
                          type: string
                          description: >-
                            ── Type & geography
                            ────────────────────────────────────────────
                        countryCode:
                          type: string
                        visibleToEntityType:
                          type: string
                          description: >-
                            ── Access / scope
                            ──────────────────────────────────────────────
                        visibleToEntityId:
                          type: string
                        accessScope:
                          type: string
                        confidenceScore:
                          type:
                            - number
                            - 'null'
                          description: >-
                            ── Confidence & provenance
                            ──────────────────────────────────────
                        creationSource:
                          type: string
                        isActive:
                          type: boolean
                          description: >-
                            ── Status
                            ──────────────────────────────────────────────────────
                        isRoot:
                          type: boolean
                        parentId:
                          type: string
                          description: >-
                            ── Hierarchy
                            ───────────────────────────────────────────────────
                        displayName:
                          type: string
                          description: >-
                            ── Naming hierarchy
                            ────────────────────────────────────────────
                        userAlias:
                          type:
                            - string
                            - 'null'
                        userAliasNotes:
                          type:
                            - string
                            - 'null'
                        effectiveName:
                          type: string
                        hasUserAlias:
                          anyOf:
                            - type: string
                            - type: boolean
                        transactionCount:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Counts
                            ──────────────────────────────────────────────────────
                        childCount:
                          type:
                            - string
                            - 'null'
                        transactionVolumes:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Service-computed nested objects
                            ─────────────────────────────
                        ownership:
                          type:
                            - string
                            - 'null'
                        relationshipSummary:
                          type:
                            - string
                            - 'null'
                        boundEntities:
                          type:
                            - string
                            - 'null'
                        entityMappings:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Deprecated compatibility fields
                            ───────────────────
                        parent:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Parent (optional, included when
                            include_parent=true) ─────────
                        metadata:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Metadata (opaque)
                            ────────────────────────────────────────────
                        establishedAt:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Timestamps
                            ──────────────────────────────────────────────────
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                        trackedAccountIds:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - counterpartIdentifier
                        - name
                        - nameLowercase
                        - type
                        - countryCode
                        - visibleToEntityType
                        - visibleToEntityId
                        - accessScope
                        - confidenceScore
                        - creationSource
                        - isActive
                        - isRoot
                        - parentId
                        - displayName
                        - userAlias
                        - userAliasNotes
                        - effectiveName
                        - hasUserAlias
                        - transactionCount
                        - childCount
                        - transactionVolumes
                        - ownership
                        - relationshipSummary
                        - boundEntities
                        - entityMappings
                        - parent
                        - metadata
                        - establishedAt
                        - createdAt
                        - updatedAt
                        - trackedAccountIds
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type:
                              - object
                              - 'null'
                          currentPage:
                            type:
                              - object
                              - 'null'
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/counterparts/available-entities:
    get:
      operationId: accounttracking.v1.counterparts.available-entities
      summary: List entities available for counterpart binding
      tags:
        - CounterpartV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      user:
                        type: array
                        prefixItems:
                          - type: object
                            properties:
                              id:
                                type: string
                              type:
                                type: string
                                const: user
                              name:
                                type: string
                            required:
                              - id
                              - type
                              - name
                        minItems: 1
                        maxItems: 1
                        additionalItems: false
                      group:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            type:
                              type: string
                            name:
                              type: string
                          required:
                            - id
                            - type
                            - name
                      tenant:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            type:
                              type: string
                            name:
                              type: string
                          required:
                            - id
                            - type
                            - name
                      global:
                        type: array
                        prefixItems:
                          - type: object
                            properties:
                              id:
                                type: string
                                const: system
                              type:
                                type: string
                                const: system
                              name:
                                type: string
                                const: Global (System-wide)
                            required:
                              - id
                              - type
                              - name
                        minItems: 1
                        maxItems: 1
                        additionalItems: false
                    required:
                      - user
                      - group
                      - tenant
                      - global
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/counterparts/access-stats:
    get:
      operationId: accounttracking.v1.counterparts.access-stats
      summary: Get the current user's counterpart access statistics
      tags:
        - CounterpartV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      total_accessible_counterparts:
                        type: integer
                      counterparts_by_scope:
                        type: string
                      counterparts_by_type:
                        type: string
                      counterparts_by_source:
                        type: string
                      own_counterparts:
                        type: integer
                      inherited_counterparts:
                        type: integer
                      high_confidence_counterparts:
                        type: integer
                      manual_counterparts:
                        type: integer
                      auto_created_counterparts:
                        type: integer
                    required:
                      - total_accessible_counterparts
                      - counterparts_by_scope
                      - counterparts_by_type
                      - counterparts_by_source
                      - own_counterparts
                      - inherited_counterparts
                      - high_confidence_counterparts
                      - manual_counterparts
                      - auto_created_counterparts
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/counterparts/for-entity:
    get:
      operationId: accounttracking.v1.counterparts.for-entity
      description: |-
        Get counterparts for an entity type/id pair.
        Uses ?entityType=...&entityId=... query params.
      summary: List counterparts bound to an entity
      tags:
        - CounterpartV1
      parameters:
        - name: page
          in: query
          description: ── v1 standard pagination ────────────────────────────────────
          schema:
            type: integer
            minimum: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: per_page
          in: query
          description: Deprecated alias of perPage
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: sort
          in: query
          schema:
            type: string
        - name: filter[name]
          in: query
          schema:
            type: string
            maxLength: 255
        - name: filter[type]
          in: query
          schema:
            type: string
        - name: filter[parentId]
          in: query
          schema:
            type: integer
        - name: filter[accessScope]
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: counterpart_identifier
          in: query
          description: ── Deprecated flat filters — prefer filter[field]=value ────────────
          schema:
            type: string
            maxLength: 255
        - name: counterpart_type
          in: query
          schema:
            type: string
        - name: country_code
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: access_scope
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: creation_source
          in: query
          schema:
            type: string
            maxLength: 50
        - name: min_confidence
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: is_manual
          in: query
          schema:
            type: boolean
        - name: startDate
          in: query
          description: ── Timeframe (both camelCase and snake_case) ─────────────────
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: start_date
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: endDate
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: end_date
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: rootsOnly
          in: query
          description: ── Include flags (both camelCase and snake_case) ─────────────
          schema:
            type: boolean
        - name: roots_only
          in: query
          schema:
            type: boolean
        - name: includeParent
          in: query
          schema:
            type: boolean
        - name: include_parent
          in: query
          schema:
            type: boolean
        - name: includeChildren
          in: query
          schema:
            type: boolean
        - name: include_children
          in: query
          schema:
            type: boolean
        - name: includeRelationships
          in: query
          schema:
            type: boolean
        - name: include_relationships
          in: query
          schema:
            type: boolean
        - name: includeBoundEntities
          in: query
          schema:
            type: boolean
        - name: include_bound_entities
          in: query
          schema:
            type: boolean
        - name: groupByParent
          in: query
          schema:
            type: boolean
        - name: group_by_parent
          in: query
          schema:
            type: boolean
        - name: minConfidence
          in: query
          description: ── Min confidence (camelCase alias) ──────────────────────────
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: accessScope
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: creationSource
          in: query
          schema:
            type: string
            maxLength: 50
        - name: entityType
          in: query
          schema:
            type: string
        - name: entityId
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            ── Core identity
                            ───────────────────────────────────────────────
                        counterpartIdentifier:
                          type: string
                        name:
                          type: string
                        nameLowercase:
                          type:
                            - string
                            - 'null'
                        type:
                          type: string
                          description: >-
                            ── Type & geography
                            ────────────────────────────────────────────
                        countryCode:
                          type: string
                        visibleToEntityType:
                          type: string
                          description: >-
                            ── Access / scope
                            ──────────────────────────────────────────────
                        visibleToEntityId:
                          type: string
                        accessScope:
                          type: string
                        confidenceScore:
                          type:
                            - number
                            - 'null'
                          description: >-
                            ── Confidence & provenance
                            ──────────────────────────────────────
                        creationSource:
                          type: string
                        isActive:
                          type: boolean
                          description: >-
                            ── Status
                            ──────────────────────────────────────────────────────
                        isRoot:
                          type: boolean
                        parentId:
                          type: string
                          description: >-
                            ── Hierarchy
                            ───────────────────────────────────────────────────
                        displayName:
                          type: string
                          description: >-
                            ── Naming hierarchy
                            ────────────────────────────────────────────
                        userAlias:
                          type:
                            - string
                            - 'null'
                        userAliasNotes:
                          type:
                            - string
                            - 'null'
                        effectiveName:
                          type: string
                        hasUserAlias:
                          anyOf:
                            - type: string
                            - type: boolean
                        transactionCount:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Counts
                            ──────────────────────────────────────────────────────
                        childCount:
                          type:
                            - string
                            - 'null'
                        transactionVolumes:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Service-computed nested objects
                            ─────────────────────────────
                        ownership:
                          type:
                            - string
                            - 'null'
                        relationshipSummary:
                          type:
                            - string
                            - 'null'
                        boundEntities:
                          type:
                            - string
                            - 'null'
                        entityMappings:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Deprecated compatibility fields
                            ───────────────────
                        parent:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Parent (optional, included when
                            include_parent=true) ─────────
                        metadata:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Metadata (opaque)
                            ────────────────────────────────────────────
                        establishedAt:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Timestamps
                            ──────────────────────────────────────────────────
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                        trackedAccountIds:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - counterpartIdentifier
                        - name
                        - nameLowercase
                        - type
                        - countryCode
                        - visibleToEntityType
                        - visibleToEntityId
                        - accessScope
                        - confidenceScore
                        - creationSource
                        - isActive
                        - isRoot
                        - parentId
                        - displayName
                        - userAlias
                        - userAliasNotes
                        - effectiveName
                        - hasUserAlias
                        - transactionCount
                        - childCount
                        - transactionVolumes
                        - ownership
                        - relationshipSummary
                        - boundEntities
                        - entityMappings
                        - parent
                        - metadata
                        - establishedAt
                        - createdAt
                        - updatedAt
                        - trackedAccountIds
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type:
                              - object
                              - 'null'
                          currentPage:
                            type:
                              - object
                              - 'null'
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/counterparts/auto-bind-transactions:
    post:
      operationId: accounttracking.v1.counterparts.auto-bind
      summary: Auto-bind transactions to counterparts from existing mappings
      tags:
        - CounterpartV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      processed:
                        type: integer
                      bound:
                        type: integer
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            counterpart_id:
                              type: string
                            error:
                              type: string
                          required:
                            - counterpart_id
                            - error
                    required:
                      - processed
                      - bound
                      - errors
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: auto_bind_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/counterparts/consolidate:
    post:
      operationId: accounttracking.v1.counterparts.consolidate
      summary: Merge duplicate counterparts into a primary one
      tags:
        - CounterpartV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                primaryId:
                  type: integer
                duplicateIds:
                  type: array
                  items:
                    type: integer
                  minItems: 1
              required:
                - primaryId
                - duplicateIds
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      successful:
                        type: array
                        items:
                          type: string
                      failed:
                        type: array
                        items:
                          anyOf:
                            - type: object
                              properties:
                                id:
                                  type: string
                                reason:
                                  type: string
                                  const: Failed to save relationship
                              required:
                                - id
                                - reason
                            - type: object
                              properties:
                                id:
                                  type: string
                                reason:
                                  type: string
                              required:
                                - id
                                - reason
                      skipped:
                        type: array
                        items:
                          anyOf:
                            - type: object
                              properties:
                                id:
                                  type: string
                                reason:
                                  type: string
                                  const: Cannot set counterpart as child of itself
                              required:
                                - id
                                - reason
                            - type: object
                              properties:
                                id:
                                  type: string
                                reason:
                                  type: string
                                  const: Already a child of this parent
                              required:
                                - id
                                - reason
                    required:
                      - successful
                      - failed
                      - skipped
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: consolidate_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Primary counterpart not found or not accessible
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/counterparts:
    get:
      operationId: accounttracking.v1.counterparts.index
      description: |-
        List counterparts accessible to the current actor.
        Accepts v1 filter[field]=value and the deprecated flat query parameters.
      summary: List counterparts accessible to the current actor
      tags:
        - CounterpartV1
      parameters:
        - name: page
          in: query
          description: ── v1 standard pagination ────────────────────────────────────
          schema:
            type: integer
            minimum: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: per_page
          in: query
          description: Deprecated alias of perPage
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: sort
          in: query
          schema:
            type: string
        - name: filter[name]
          in: query
          schema:
            type: string
            maxLength: 255
        - name: filter[type]
          in: query
          schema:
            type: string
        - name: filter[parentId]
          in: query
          schema:
            type: integer
        - name: filter[accessScope]
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: counterpart_identifier
          in: query
          description: ── Deprecated flat filters — prefer filter[field]=value ────────────
          schema:
            type: string
            maxLength: 255
        - name: counterpart_type
          in: query
          schema:
            type: string
        - name: country_code
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: access_scope
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: creation_source
          in: query
          schema:
            type: string
            maxLength: 50
        - name: min_confidence
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: is_manual
          in: query
          schema:
            type: boolean
        - name: startDate
          in: query
          description: ── Timeframe (both camelCase and snake_case) ─────────────────
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: start_date
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: endDate
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: end_date
          in: query
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: rootsOnly
          in: query
          description: ── Include flags (both camelCase and snake_case) ─────────────
          schema:
            type: boolean
        - name: roots_only
          in: query
          schema:
            type: boolean
        - name: includeParent
          in: query
          schema:
            type: boolean
        - name: include_parent
          in: query
          schema:
            type: boolean
        - name: includeChildren
          in: query
          schema:
            type: boolean
        - name: include_children
          in: query
          schema:
            type: boolean
        - name: includeRelationships
          in: query
          schema:
            type: boolean
        - name: include_relationships
          in: query
          schema:
            type: boolean
        - name: includeBoundEntities
          in: query
          schema:
            type: boolean
        - name: include_bound_entities
          in: query
          schema:
            type: boolean
        - name: groupByParent
          in: query
          schema:
            type: boolean
        - name: group_by_parent
          in: query
          schema:
            type: boolean
        - name: minConfidence
          in: query
          description: ── Min confidence (camelCase alias) ──────────────────────────
          schema:
            type: number
            minimum: 0
            maximum: 1
        - name: accessScope
          in: query
          schema:
            type: string
            enum:
              - private
              - user
              - group
              - tenant
              - global
        - name: creationSource
          in: query
          schema:
            type: string
            maxLength: 50
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            ── Core identity
                            ───────────────────────────────────────────────
                        counterpartIdentifier:
                          type: string
                        name:
                          type: string
                        nameLowercase:
                          type:
                            - string
                            - 'null'
                        type:
                          type: string
                          description: >-
                            ── Type & geography
                            ────────────────────────────────────────────
                        countryCode:
                          type: string
                        visibleToEntityType:
                          type: string
                          description: >-
                            ── Access / scope
                            ──────────────────────────────────────────────
                        visibleToEntityId:
                          type: string
                        accessScope:
                          type: string
                        confidenceScore:
                          type:
                            - number
                            - 'null'
                          description: >-
                            ── Confidence & provenance
                            ──────────────────────────────────────
                        creationSource:
                          type: string
                        isActive:
                          type: boolean
                          description: >-
                            ── Status
                            ──────────────────────────────────────────────────────
                        isRoot:
                          type: boolean
                        parentId:
                          type: string
                          description: >-
                            ── Hierarchy
                            ───────────────────────────────────────────────────
                        displayName:
                          type: string
                          description: >-
                            ── Naming hierarchy
                            ────────────────────────────────────────────
                        userAlias:
                          type:
                            - string
                            - 'null'
                        userAliasNotes:
                          type:
                            - string
                            - 'null'
                        effectiveName:
                          type: string
                        hasUserAlias:
                          anyOf:
                            - type: string
                            - type: boolean
                        transactionCount:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Counts
                            ──────────────────────────────────────────────────────
                        childCount:
                          type:
                            - string
                            - 'null'
                        transactionVolumes:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Service-computed nested objects
                            ─────────────────────────────
                        ownership:
                          type:
                            - string
                            - 'null'
                        relationshipSummary:
                          type:
                            - string
                            - 'null'
                        boundEntities:
                          type:
                            - string
                            - 'null'
                        entityMappings:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Deprecated compatibility fields
                            ───────────────────
                        parent:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Parent (optional, included when
                            include_parent=true) ─────────
                        metadata:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Metadata (opaque)
                            ────────────────────────────────────────────
                        establishedAt:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Timestamps
                            ──────────────────────────────────────────────────
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                        trackedAccountIds:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - counterpartIdentifier
                        - name
                        - nameLowercase
                        - type
                        - countryCode
                        - visibleToEntityType
                        - visibleToEntityId
                        - accessScope
                        - confidenceScore
                        - creationSource
                        - isActive
                        - isRoot
                        - parentId
                        - displayName
                        - userAlias
                        - userAliasNotes
                        - effectiveName
                        - hasUserAlias
                        - transactionCount
                        - childCount
                        - transactionVolumes
                        - ownership
                        - relationshipSummary
                        - boundEntities
                        - entityMappings
                        - parent
                        - metadata
                        - establishedAt
                        - createdAt
                        - updatedAt
                        - trackedAccountIds
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type:
                              - object
                              - 'null'
                          currentPage:
                            type:
                              - object
                              - 'null'
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
    post:
      operationId: accounttracking.v1.counterparts.store
      description: |-
        Create a new counterpart entity.
        Returns 201 + Location header.
      summary: Create a new counterpart entity
      tags:
        - CounterpartV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreCounterpartV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: counterpart_create_failed
                      message:
                        type: string
                        const: Failed to create counterpart
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/counterparts/{counterpart}:
    get:
      operationId: accounttracking.v1.counterparts.show
      description: Fetch a single counterpart with full rich shape.
      summary: Fetch a single counterpart with full detail
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: accounttracking.v1.counterparts.update
      description: >-
        Update a counterpart. Now accepts country_code, confidence_score,
        metadata.
      summary: Update a counterpart's attributes
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCounterpartV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: counterpart_update_failed
                      message:
                        type: string
                        const: Failed to update counterpart
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: accounttracking.v1.counterparts.destroy
      description: |-
        Delete a counterpart.
        Returns 204 No Content.
      summary: Deactivate a counterpart
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: counterpart_delete_failed
                      message:
                        type: string
                        const: Failed to delete counterpart
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/counterparts/{counterpart}/alias:
    get:
      operationId: accounttracking.v1.counterparts.alias
      summary: Get the current user's alias for a counterpart
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      counterpartId:
                        type: integer
                      alias: {}
                    required:
                      - counterpartId
                      - alias
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: accounttracking.v1.counterparts.alias.set
      summary: Set the current user's alias for a counterpart
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetAliasV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      counterpartId:
                        type: integer
                      alias: {}
                    required:
                      - counterpartId
                      - alias
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: alias_set_failed
                      message:
                        type: string
                        const: Failed to set alias
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: accounttracking.v1.counterparts.alias.remove
      summary: Remove the current user's alias for a counterpart
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: alias_remove_failed
                      message:
                        type: string
                        const: Failed to remove alias
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/counterparts/{counterpart}/display-name:
    put:
      operationId: accounttracking.v1.counterparts.display-name
      summary: Set a counterpart's display name
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetDisplayNameV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: display_name_failed
                      message:
                        type: string
                        const: Failed to set display name
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/counterparts/{counterpart}/bind-entity:
    post:
      operationId: accounttracking.v1.counterparts.bind-entity
      summary: Bind a counterpart to an entity
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindEntityV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      counterpartId:
                        type: integer
                      entityId: {}
                      entityType: {}
                    required:
                      - counterpartId
                      - entityId
                      - entityType
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bind_entity_failed
                      message:
                        type: string
                        const: Failed to bind entity
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/counterparts/{counterpart}/unbind-entity:
    delete:
      operationId: accounttracking.v1.counterparts.unbind-entity
      summary: Unbind a counterpart from an entity
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: unbind_entity_failed
                      message:
                        type: string
                        const: Failed to unbind entity
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_error
                      message:
                        type: string
                        const: entityId and entityType are required
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/counterparts/{counterpart}/bind-transactions:
    post:
      operationId: accounttracking.v1.counterparts.bind-transactions
      summary: Bind transactions to a counterpart
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/BindTransactionsV1Request'
                - type: object
                  properties:
                    transaction_ids:
                      type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      counterpartId:
                        type: integer
                      boundCount:
                        type: integer
                      results:
                        type: object
                        properties:
                          successful:
                            type: array
                            items:
                              type: string
                          failed:
                            type: array
                            items:
                              type: object
                              properties:
                                transaction_id:
                                  type: string
                                error:
                                  type: string
                              required:
                                - transaction_id
                                - error
                          already_bound:
                            type: array
                            items:
                              type: string
                        required:
                          - successful
                          - failed
                          - already_bound
                    required:
                      - counterpartId
                      - boundCount
                      - results
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bind_transactions_failed
                      message:
                        type: string
                        const: Failed to bind transactions
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/counterparts/{counterpart}/transactions:
    get:
      operationId: accounttracking.v1.counterparts.transactions
      description: Cursor-paginated transactions linked to a counterpart.
      summary: List transactions linked to a counterpart
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: cursor
          in: query
          schema:
            type: string
        - name: filter[fromDate]
          in: query
          schema:
            type: string
        - name: filter[toDate]
          in: query
          schema:
            type: string
        - name: filter[accountId]
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Core identifiers
                        transactionId:
                          type: string
                        internalTransactionId:
                          type: string
                          description: alias of partner_transaction_id
                        physicalAccountId:
                          type: string
                        transactionAmount:
                          type: number
                          description: >-
                            Amounts / currency (both canonical names + backward
                            aliases)
                        amount:
                          type: number
                        signedAmount:
                          type: string
                          description: alias — kept for old consumers
                        currencyCode:
                          type: string
                        currency:
                          type: string
                        sourceCurrency:
                          type: string
                          description: alias — kept for old consumers
                        targetCurrency:
                          type: string
                        exchangeRate:
                          type:
                            - number
                            - 'null'
                        bookingDate:
                          type: string
                          description: Dates (Y-m-d strings — NOT ISO-8601 timestamps)
                        valueDate:
                          type: string
                        debtorIban:
                          type: string
                          description: Debtor
                        debtorBban:
                          type: string
                        debtorName:
                          type: string
                        debtorBankName:
                          type: string
                        debtorRemittanceInformation:
                          type: string
                        creditorIban:
                          type: string
                          description: Creditor
                        creditorBban:
                          type: string
                        creditorName:
                          type: string
                        creditorBankName:
                          type: string
                        creditorRemittanceInformation:
                          type: string
                        direction:
                          type: string
                          description: Processed / counterpart fields
                        counterpartAccountNumber:
                          type: string
                        counterpartName:
                          type: string
                        remittanceInformation:
                          type: string
                        description:
                          type: string
                        counterpartyBankName:
                          type: string
                          description: alias
                        countryCode:
                          type: string
                        countryCodeConfidence:
                          type:
                            - number
                            - 'null'
                        countryCodeMethod:
                          type: string
                        transactionType:
                          type: string
                          description: Transaction type (deprecated alias + canonical)
                        type:
                          type: string
                          description: alias
                        canonicalType:
                          type: string
                          description: |-
                            alias
                            Enhanced classification
                        canonicalTypeLabel:
                          type: string
                        canonicalSubtype:
                          type: string
                        canonicalChannel:
                          type: string
                        canonicalChannelLabel:
                          type: string
                        canonicalScheme:
                          type: string
                        canonicalPurpose:
                          type: string
                        classificationConfidence:
                          type:
                            - number
                            - 'null'
                        classificationMethod:
                          type: string
                        classificationCountry:
                          type: string
                        classificationProvider:
                          type: string
                        merchantCategoryCode:
                          type: string
                          description: Additional metadata
                        transactionStatus:
                          type: string
                        status:
                          type: string
                        transactionMetadata:
                          type: string
                          description: alias
                        mandateId:
                          type: string
                        referenceNumber:
                          type: string
                        isReversal:
                          type: boolean
                        counterpartType:
                          description: Counterpart classification
                          anyOf:
                            - type: string
                            - type: string
                              enum:
                                - other
                        counterpartTypeLabel:
                          anyOf:
                            - type: string
                            - type: string
                              enum:
                                - Other
                        counterpartTypeConfidence:
                          type:
                            - number
                            - 'null'
                        counterpartTypeMethod:
                          type: string
                        companyId:
                          type: string
                          description: Company binding (camelCase only — v1 contract)
                        company:
                          type:
                            - object
                            - 'null'
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            organizationNumber:
                              type:
                                - string
                                - 'null'
                          required:
                            - id
                            - name
                            - organizationNumber
                        companyBindingSource:
                          type: string
                        companyBindingConfidence:
                          type:
                            - number
                            - 'null'
                        companyBoundAt:
                          type:
                            - string
                            - 'null'
                        companyBoundBy:
                          type: string
                        counterpartEntityId:
                          type: string
                          description: Counterpart entity
                        counterpart:
                          type:
                            - object
                            - 'null'
                          properties:
                            id:
                              type: string
                            counterpartName:
                              type: string
                            displayName:
                              type: string
                            effectiveName:
                              type: string
                            userAlias:
                              type: string
                            userAliasNotes:
                              type: string
                            hasUserAlias:
                              type: boolean
                            type:
                              type:
                                - string
                                - 'null'
                            countryCode:
                              type: string
                            isRoot:
                              type: string
                            directCounterpart:
                              type: object
                              properties:
                                id:
                                  type: string
                                counterpartName:
                                  type: string
                                displayName:
                                  type: string
                              required:
                                - id
                                - counterpartName
                                - displayName
                          required:
                            - id
                            - counterpartName
                            - displayName
                            - effectiveName
                            - userAlias
                            - userAliasNotes
                            - hasUserAlias
                            - type
                            - countryCode
                            - isRoot
                            - directCounterpart
                        isCardTransaction:
                          type: string
                          description: Computed classification flags
                        isInstantPayment:
                          type: string
                        isFee:
                          type: string
                        isTransfer:
                          type: string
                        hasHighConfidence:
                          type: string
                        needsReclassification:
                          type: string
                        hasCounterpartClassification:
                          type: string
                        hasHighCounterpartConfidence:
                          type: string
                        needsCounterpartClassification:
                          type: string
                        boundCompanyId:
                          type: string
                          description: >-
                            Backward-compat extras from controller
                            ->additional()
                        boundCompanyName:
                          type:
                            - string
                            - 'null'
                        raw:
                          type: string
                          description: >-
                            Raw provider data (opaque blob — verbatim, no key
                            transformation)
                        createdAt:
                          type:
                            - string
                            - 'null'
                          description: Timestamps (ISO-8601 UTC)
                        updatedAt:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - transactionId
                        - internalTransactionId
                        - physicalAccountId
                        - transactionAmount
                        - amount
                        - signedAmount
                        - currencyCode
                        - currency
                        - sourceCurrency
                        - targetCurrency
                        - exchangeRate
                        - bookingDate
                        - valueDate
                        - debtorIban
                        - debtorBban
                        - debtorName
                        - debtorBankName
                        - debtorRemittanceInformation
                        - creditorIban
                        - creditorBban
                        - creditorName
                        - creditorBankName
                        - creditorRemittanceInformation
                        - direction
                        - counterpartAccountNumber
                        - counterpartName
                        - remittanceInformation
                        - description
                        - counterpartyBankName
                        - countryCode
                        - countryCodeConfidence
                        - countryCodeMethod
                        - transactionType
                        - type
                        - canonicalType
                        - canonicalTypeLabel
                        - canonicalSubtype
                        - canonicalChannel
                        - canonicalChannelLabel
                        - canonicalScheme
                        - canonicalPurpose
                        - classificationConfidence
                        - classificationMethod
                        - classificationCountry
                        - classificationProvider
                        - merchantCategoryCode
                        - transactionStatus
                        - status
                        - transactionMetadata
                        - mandateId
                        - referenceNumber
                        - isReversal
                        - counterpartType
                        - counterpartTypeLabel
                        - counterpartTypeConfidence
                        - counterpartTypeMethod
                        - companyId
                        - company
                        - companyBindingSource
                        - companyBindingConfidence
                        - companyBoundAt
                        - companyBoundBy
                        - counterpartEntityId
                        - counterpart
                        - isCardTransaction
                        - isInstantPayment
                        - isFee
                        - isTransfer
                        - hasHighConfidence
                        - needsReclassification
                        - hasCounterpartClassification
                        - hasHighCounterpartConfidence
                        - needsCounterpartClassification
                        - boundCompanyId
                        - boundCompanyName
                        - raw
                        - createdAt
                        - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          perPage:
                            type:
                              - object
                              - 'null'
                          nextCursor:
                            type: string
                          prevCursor: {}
                        required:
                          - perPage
                          - nextCursor
                          - prevCursor
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: transactions_fetch_failed
                      message:
                        type: string
                        const: Failed to fetch transactions
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/counterparts/{counterpart}/family-tree:
    get:
      operationId: accounttracking.v1.counterparts.family-tree
      description: 'v1 exception: returns snake_case service output (documented).'
      summary: Get a counterpart's family tree
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      root:
                        type: object
                        properties:
                          id:
                            type: integer
                          counterpart_identifier:
                            type: string
                          counterpart_name:
                            type:
                              - string
                              - 'null'
                          display_name:
                            type: string
                          counterpart_type:
                            type: string
                          confidence_score:
                            type:
                              - string
                              - 'null'
                          creation_source:
                            type: string
                          established_at:
                            type: string
                          transaction_count:
                            type: integer
                          relationship_summary:
                            anyOf:
                              - type: object
                                properties:
                                  parent_id:
                                    type:
                                      - integer
                                      - 'null'
                                  has_parent:
                                    type: boolean
                                  has_children:
                                    type: boolean
                                  child_count:
                                    type: integer
                                  sibling_count:
                                    type: integer
                                  depth_level:
                                    type: integer
                                  is_root:
                                    type: boolean
                                  is_leaf:
                                    type: boolean
                                required:
                                  - parent_id
                                  - has_parent
                                  - has_children
                                  - child_count
                                  - sibling_count
                                  - depth_level
                                  - is_root
                                  - is_leaf
                              - type: object
                                properties:
                                  parent_id:
                                    type:
                                      - integer
                                      - 'null'
                                  has_parent:
                                    type: boolean
                                  has_children:
                                    type: boolean
                                  child_count:
                                    type: integer
                                  sibling_count:
                                    type: integer
                                  depth_level:
                                    type: 'null'
                                  is_root:
                                    type: boolean
                                    description: >-
                                      Skip complex calculation in optimized
                                      version
                                  is_leaf:
                                    type: boolean
                                required:
                                  - parent_id
                                  - has_parent
                                  - has_children
                                  - child_count
                                  - sibling_count
                                  - depth_level
                                  - is_root
                                  - is_leaf
                        required:
                          - id
                          - counterpart_identifier
                          - counterpart_name
                          - display_name
                          - counterpart_type
                          - confidence_score
                          - creation_source
                          - established_at
                          - transaction_count
                          - relationship_summary
                      tree:
                        type: object
                        properties:
                          id:
                            type: integer
                          counterpart_identifier:
                            type: string
                          counterpart_name:
                            type:
                              - string
                              - 'null'
                          display_name:
                            type: string
                          counterpart_type:
                            type: string
                          confidence_score:
                            type:
                              - string
                              - 'null'
                          creation_source:
                            type: string
                          established_at:
                            type: string
                          transaction_count:
                            type: integer
                          relationship_summary:
                            anyOf:
                              - type: object
                                properties:
                                  parent_id:
                                    type:
                                      - integer
                                      - 'null'
                                  has_parent:
                                    type: boolean
                                  has_children:
                                    type: boolean
                                  child_count:
                                    type: integer
                                  sibling_count:
                                    type: integer
                                  depth_level:
                                    type: integer
                                  is_root:
                                    type: boolean
                                  is_leaf:
                                    type: boolean
                                required:
                                  - parent_id
                                  - has_parent
                                  - has_children
                                  - child_count
                                  - sibling_count
                                  - depth_level
                                  - is_root
                                  - is_leaf
                              - type: object
                                properties:
                                  parent_id:
                                    type:
                                      - integer
                                      - 'null'
                                  has_parent:
                                    type: boolean
                                  has_children:
                                    type: boolean
                                  child_count:
                                    type: integer
                                  sibling_count:
                                    type: integer
                                  depth_level:
                                    type: 'null'
                                  is_root:
                                    type: boolean
                                    description: >-
                                      Skip complex calculation in optimized
                                      version
                                  is_leaf:
                                    type: boolean
                                required:
                                  - parent_id
                                  - has_parent
                                  - has_children
                                  - child_count
                                  - sibling_count
                                  - depth_level
                                  - is_root
                                  - is_leaf
                          children:
                            type: array
                            items:
                              type: array
                              items: {}
                        required:
                          - id
                          - counterpart_identifier
                          - counterpart_name
                          - display_name
                          - counterpart_type
                          - confidence_score
                          - creation_source
                          - established_at
                          - transaction_count
                          - relationship_summary
                          - children
                      current_counterpart_id:
                        type: integer
                      tree_stats:
                        type: object
                        properties:
                          total_members:
                            type: string
                          max_depth:
                            type: integer
                        required:
                          - total_members
                          - max_depth
                    required:
                      - root
                      - tree
                      - current_counterpart_id
                      - tree_stats
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/counterparts/{counterpart}/find-related:
    get:
      operationId: accounttracking.v1.counterparts.find-related
      description: 'v1 exception: returns snake_case service output (documented).'
      summary: Find counterparts related by name/IBAN similarity
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      related_counterparts:
                        type: array
                        items: {}
                      total_found:
                        type: integer
                    required:
                      - related_counterparts
                      - total_found
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/counterparts/{counterpart}/relationships:
    get:
      operationId: accounttracking.v1.counterparts.relationships
      description: 'v1 exception: returns snake_case service output (documented).'
      summary: Get a counterpart's parent, children, and siblings
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      parent:
                        type: object
                        properties:
                          id:
                            type: integer
                          counterpart_identifier:
                            type: string
                          counterpart_name:
                            type:
                              - string
                              - 'null'
                          display_name:
                            type: string
                          transaction_count:
                            type: integer
                        required:
                          - id
                          - counterpart_identifier
                          - counterpart_name
                          - display_name
                          - transaction_count
                      children:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            counterpart_identifier:
                              type: string
                            counterpart_name:
                              type: string
                            display_name:
                              type: string
                            transaction_count:
                              type: string
                          required:
                            - id
                            - counterpart_identifier
                            - counterpart_name
                            - display_name
                            - transaction_count
                      siblings:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            counterpart_identifier:
                              type: string
                            counterpart_name:
                              type: string
                            display_name:
                              type: string
                            transaction_count:
                              type: string
                          required:
                            - id
                            - counterpart_identifier
                            - counterpart_name
                            - display_name
                            - transaction_count
                      summary:
                        anyOf:
                          - type: object
                            properties:
                              parent_id:
                                type:
                                  - integer
                                  - 'null'
                              has_parent:
                                type: boolean
                              has_children:
                                type: boolean
                              child_count:
                                type: integer
                              sibling_count:
                                type: integer
                              depth_level:
                                type: integer
                              is_root:
                                type: boolean
                              is_leaf:
                                type: boolean
                            required:
                              - parent_id
                              - has_parent
                              - has_children
                              - child_count
                              - sibling_count
                              - depth_level
                              - is_root
                              - is_leaf
                          - type: object
                            properties:
                              parent_id:
                                type:
                                  - integer
                                  - 'null'
                              has_parent:
                                type: boolean
                              has_children:
                                type: boolean
                              child_count:
                                type: integer
                              sibling_count:
                                type: integer
                              depth_level:
                                type: 'null'
                              is_root:
                                type: boolean
                                description: Skip complex calculation in optimized version
                              is_leaf:
                                type: boolean
                            required:
                              - parent_id
                              - has_parent
                              - has_children
                              - child_count
                              - sibling_count
                              - depth_level
                              - is_root
                              - is_leaf
                    required:
                      - parent
                      - children
                      - siblings
                      - summary
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/counterparts/{counterpart}/link-as-child:
    post:
      operationId: accounttracking.v1.counterparts.link-as-child
      summary: Link a counterpart as a child of another
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentId:
                  type: integer
              required:
                - parentId
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      counterpartId:
                        type: integer
                      parentId:
                        type: string
                      linked:
                        type: boolean
                    required:
                      - counterpartId
                      - parentId
                      - linked
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: link_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/counterparts/{counterpart}/unlink-from-parent:
    delete:
      operationId: accounttracking.v1.counterparts.unlink-from-parent
      summary: Unlink a counterpart from its parent
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: unlink_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/counterparts/{counterpart}/set-parent:
    post:
      operationId: accounttracking.v1.counterparts.set-parent
      summary: Set a counterpart's parent
      tags:
        - CounterpartV1
      parameters:
        - name: counterpart
          in: path
          required: true
          description: The counterpart ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentId:
                  type: integer
              required:
                - parentId
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      counterpartId:
                        type: integer
                      parentId:
                        type: string
                    required:
                      - counterpartId
                      - parentId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: set_parent_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /datasets/v1/profiles:
    get:
      operationId: datasets.v1.profiles.index
      description: >-
        Returns active profiles filtered by entity/profession, merged with
        global

        profiles, de-duplicated by id.
      summary: List accessible dataset profiles
      tags:
        - DatasetProfileV1
      parameters:
        - name: entity_id
          in: query
          schema:
            type: string
        - name: entity_type
          in: query
          schema:
            type: string
        - name: profession
          in: query
          schema:
            type: string
        - name: sub_profession
          in: query
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DatasetProfileV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve dataset profiles
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    post:
      operationId: datasets.v1.profiles.store
      summary: Create a dataset profile
      tags:
        - DatasetProfileV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreDatasetProfileV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DatasetProfileV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to create dataset profile
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /datasets/v1/profiles/{id}:
    put:
      operationId: datasets.v1.profiles.update
      summary: Update a dataset profile
      tags:
        - DatasetProfileV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatasetProfileV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DatasetProfileV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Dataset profile not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to update dataset profile
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    delete:
      operationId: datasets.v1.profiles.destroy
      description: Returns 204 No Content on success.
      summary: Delete a dataset profile
      tags:
        - DatasetProfileV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Dataset profile not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to delete dataset profile
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /datasets/v1/profiles/{id}/increment-usage:
    post:
      operationId: datasets.v1.profiles.increment-usage
      description: >-
        Safe to call repeatedly; this action does not require an Idempotency-Key
        header.
      summary: Increment a dataset profile's usage count
      tags:
        - DatasetProfileV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      usageCount:
                        type: integer
                    required:
                      - usageCount
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Dataset profile not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to increment profile usage
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /datasets/v1/subset-types:
    get:
      operationId: datasets.v1.subset-types.index
      summary: List dataset subset types
      tags:
        - DatasetV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DatasetSubsetTypeV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve subset types
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /datasets/v1:
    get:
      operationId: datasets.v1.index
      description: >-
        Returns datasets whose groups are in the user's accessible company IDs,
        with

        optional provider/entity filters. Accepts `perPage` (or the deprecated

        `per_page`, default 15).
      summary: List accessible datasets
      tags:
        - DatasetV1
      parameters:
        - name: provider_id
          in: query
          schema:
            type: string
        - name: entity_id
          in: query
          schema:
            type: string
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DatasetV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve datasets
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /datasets/v1/{id}:
    get:
      operationId: datasets.v1.show
      description: Returns a single accessible dataset with subsets and groups loaded.
      summary: Retrieve a single dataset
      tags:
        - DatasetV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DatasetV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Dataset not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve dataset
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /entitypermissions/v1/entities/{entityType}/{entityId}/users/{userId}/effective-permissions:
    get:
      operationId: entitypermissions.v1.entities.users.effective-permissions
      summary: Get a user's effective permissions on an entity
      tags:
        - EffectivePermissionsV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: with_sources
          in: query
          schema:
            type: boolean
        - name: check_inheritance
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EffectivePermissionsV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitypermissions/v1/entities/{entityType}/{entityId}/users/{userId}/cache:
    delete:
      operationId: entitypermissions.v1.entities.users.cache.destroy
      summary: Clear cached effective permissions for a user
      tags:
        - EffectivePermissionsV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      userId:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: integer
                      cleared:
                        type: boolean
                    required:
                      - userId
                      - entityType
                      - entityId
                      - cleared
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /entitymanagement/v1/{entityType}/{entityId}/addresses:
    get:
      operationId: entitymanagement.v1.addresses.index
      summary: Get all addresses for an entity
      tags:
        - EntityAddress
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityAddressResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    post:
      operationId: entitymanagement.v1.addresses.store
      summary: Create a new address for an entity.
      tags:
        - EntityAddress
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreEntityAddressRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      entityType:
                        type: string
                      entityId:
                        type: string
                      addressType:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      addressLine1:
                        type:
                          - string
                          - 'null'
                      addressLine2:
                        type:
                          - string
                          - 'null'
                      city:
                        type:
                          - string
                          - 'null'
                      stateProvince:
                        type:
                          - string
                          - 'null'
                      postalCode:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - addressType
                      - label
                      - addressLine1
                      - addressLine2
                      - city
                      - stateProvince
                      - postalCode
                      - countryCode
                      - isPrimary
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/{entityType}/{entityId}/addresses/{addressId}:
    get:
      operationId: entitymanagement.v1.addresses.show
      summary: Get a specific address
      tags:
        - EntityAddress
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: addressId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      entityType:
                        type: string
                      entityId:
                        type: string
                      addressType:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      addressLine1:
                        type:
                          - string
                          - 'null'
                      addressLine2:
                        type:
                          - string
                          - 'null'
                      city:
                        type:
                          - string
                          - 'null'
                      stateProvince:
                        type:
                          - string
                          - 'null'
                      postalCode:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - addressType
                      - label
                      - addressLine1
                      - addressLine2
                      - city
                      - stateProvince
                      - postalCode
                      - countryCode
                      - isPrimary
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Address not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
    put:
      operationId: entitymanagement.v1.addresses.update
      summary: Update an address (PUT = full replace, PATCH = partial)
      tags:
        - EntityAddress
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: addressId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntityAddressRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      entityType:
                        type: string
                      entityId:
                        type: string
                      addressType:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      addressLine1:
                        type:
                          - string
                          - 'null'
                      addressLine2:
                        type:
                          - string
                          - 'null'
                      city:
                        type:
                          - string
                          - 'null'
                      stateProvince:
                        type:
                          - string
                          - 'null'
                      postalCode:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - addressType
                      - label
                      - addressLine1
                      - addressLine2
                      - city
                      - stateProvince
                      - postalCode
                      - countryCode
                      - isPrimary
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Address not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: entitymanagement.v1.addresses.patch
      summary: Update an address (PUT = full replace, PATCH = partial)
      tags:
        - EntityAddress
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: addressId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntityAddressRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      entityType:
                        type: string
                      entityId:
                        type: string
                      addressType:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      addressLine1:
                        type:
                          - string
                          - 'null'
                      addressLine2:
                        type:
                          - string
                          - 'null'
                      city:
                        type:
                          - string
                          - 'null'
                      stateProvince:
                        type:
                          - string
                          - 'null'
                      postalCode:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - addressType
                      - label
                      - addressLine1
                      - addressLine2
                      - city
                      - stateProvince
                      - postalCode
                      - countryCode
                      - isPrimary
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Address not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: entitymanagement.v1.addresses.destroy
      summary: Delete an address.
      tags:
        - EntityAddress
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: addressId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Address not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /entitymanagement/v1/{entityType}/{entityId}/addresses/{addressId}/set-primary:
    post:
      operationId: entitymanagement.v1.addresses.set-primary
      summary: Set an address as primary
      tags:
        - EntityAddress
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: addressId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      entityType:
                        type: string
                      entityId:
                        type: string
                      addressType:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      addressLine1:
                        type:
                          - string
                          - 'null'
                      addressLine2:
                        type:
                          - string
                          - 'null'
                      city:
                        type:
                          - string
                          - 'null'
                      stateProvince:
                        type:
                          - string
                          - 'null'
                      postalCode:
                        type:
                          - string
                          - 'null'
                      countryCode:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - addressType
                      - label
                      - addressLine1
                      - addressLine2
                      - city
                      - stateProvince
                      - postalCode
                      - countryCode
                      - isPrimary
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Address not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /apps/v1/connections:
    get:
      operationId: apps.v1.connections.index
      summary: Every Connection installed on the operating
      tags:
        - EntityConnectionV1
      parameters:
        - name: filter[status]
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityConnectionResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /apps/v1/connections/{connection}:
    delete:
      operationId: apps.v1.connections.destroy
      summary: Revoke a connection
      tags:
        - EntityConnectionV1
      parameters:
        - name: connection
          in: path
          required: true
          description: The connection ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /entitymanagement/v1/{entityType}/{entityId}/contacts:
    get:
      operationId: entitymanagement.v1.contacts.index
      summary: Get all contacts for an entity.
      tags:
        - EntityContact
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: type
          in: query
          schema:
            type: string
        - name: verified
          in: query
          schema:
            type: boolean
            default: false
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityContactResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    post:
      operationId: entitymanagement.v1.contacts.store
      summary: Create a new contact for an entity.
      tags:
        - EntityContact
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreEntityContactRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      contactType:
                        type: string
                      contactValue:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isVerified:
                        type: boolean
                      verifiedAt:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - contactType
                      - contactValue
                      - label
                      - isPrimary
                      - isVerified
                      - verifiedAt
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/{entityType}/{entityId}/contacts/{contactId}:
    get:
      operationId: entitymanagement.v1.contacts.show
      summary: Get a specific contact
      tags:
        - EntityContact
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: contactId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      contactType:
                        type: string
                      contactValue:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isVerified:
                        type: boolean
                      verifiedAt:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - contactType
                      - contactValue
                      - label
                      - isPrimary
                      - isVerified
                      - verifiedAt
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Contact not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
    put:
      operationId: entitymanagement.v1.contacts.update
      summary: Update a contact (PUT = full replace, PATCH = partial)
      tags:
        - EntityContact
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: contactId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntityContactRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      contactType:
                        type: string
                      contactValue:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isVerified:
                        type: boolean
                      verifiedAt:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - contactType
                      - contactValue
                      - label
                      - isPrimary
                      - isVerified
                      - verifiedAt
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Contact not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: entitymanagement.v1.contacts.patch
      summary: Update a contact (PUT = full replace, PATCH = partial)
      tags:
        - EntityContact
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: contactId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntityContactRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      contactType:
                        type: string
                      contactValue:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isVerified:
                        type: boolean
                      verifiedAt:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - contactType
                      - contactValue
                      - label
                      - isPrimary
                      - isVerified
                      - verifiedAt
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Contact not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: entitymanagement.v1.contacts.destroy
      summary: Delete a contact.
      tags:
        - EntityContact
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: contactId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Contact not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /entitymanagement/v1/{entityType}/{entityId}/contacts/{contactId}/set-primary:
    post:
      operationId: entitymanagement.v1.contacts.set-primary
      summary: Set a contact as primary
      tags:
        - EntityContact
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: contactId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      contactType:
                        type: string
                      contactValue:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isVerified:
                        type: boolean
                      verifiedAt:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - contactType
                      - contactValue
                      - label
                      - isPrimary
                      - isVerified
                      - verifiedAt
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Contact not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /entitymanagement/v1/{entityType}/{entityId}/contacts/{contactId}/verify:
    post:
      operationId: entitymanagement.v1.contacts.verify
      summary: Verify a contact
      tags:
        - EntityContact
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: contactId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      contactType:
                        type: string
                      contactValue:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                      isPrimary:
                        type: boolean
                      isVerified:
                        type: boolean
                      verifiedAt:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - contactType
                      - contactValue
                      - label
                      - isPrimary
                      - isVerified
                      - verifiedAt
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Contact not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /entitypermissions/v1/entities/{entityType}/{entityId}/hierarchy:
    get:
      operationId: entitypermissions.v1.entities.hierarchy
      tags:
        - EntityHierarchyV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: include_role_counts
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EntityHierarchyV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      summary: Hierarchy entities
  /entitymanagement/v1/{entityType}/{entityId}/invitations:
    get:
      operationId: entitymanagement.v1.invitations.index
      summary: List pending invitations issued by the host entity.
      tags:
        - EntityInvitation
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvitationResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: entitymanagement.v1.invitations.store
      summary: Create (send) a new invitation from the host entity.
      tags:
        - EntityInvitation
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvitationRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      parentEntityType:
                        type: string
                      parentEntityId:
                        type: string
                      childEntityType:
                        type: string
                      childEntityId:
                        type: string
                      relationshipType:
                        type: string
                      status:
                        type: string
                      invitationToken:
                        type: string
                      invitationTokenExpiresAt:
                        type:
                          - string
                          - 'null'
                      invitedAt:
                        type:
                          - string
                          - 'null'
                      acceptedAt:
                        type:
                          - string
                          - 'null'
                      rejectedAt:
                        type:
                          - string
                          - 'null'
                      suspendedAt:
                        type:
                          - string
                          - 'null'
                      invitedBy:
                        type: string
                      invitationMessage:
                        type: string
                      requestedRoleKey:
                        type: string
                      establishedBy:
                        type: string
                      establishedAt:
                        type:
                          - string
                          - 'null'
                      expiresAt:
                        type:
                          - string
                          - 'null'
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - parentEntityType
                      - parentEntityId
                      - childEntityType
                      - childEntityId
                      - relationshipType
                      - status
                      - invitationToken
                      - invitationTokenExpiresAt
                      - invitedAt
                      - acceptedAt
                      - rejectedAt
                      - suspendedAt
                      - invitedBy
                      - invitationMessage
                      - requestedRoleKey
                      - establishedBy
                      - establishedAt
                      - expiresAt
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/{entityType}/{entityId}/invitations/{id}:
    delete:
      operationId: entitymanagement.v1.invitations.destroy
      summary: Revoke a pending invitation issued by the host entity.
      tags:
        - EntityInvitation
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      parentEntityType:
                        type: string
                      parentEntityId:
                        type: string
                      childEntityType:
                        type: string
                      childEntityId:
                        type: string
                      relationshipType:
                        type: string
                      status:
                        type: string
                      invitationToken:
                        type: string
                      invitationTokenExpiresAt:
                        type:
                          - string
                          - 'null'
                      invitedAt:
                        type:
                          - string
                          - 'null'
                      acceptedAt:
                        type:
                          - string
                          - 'null'
                      rejectedAt:
                        type:
                          - string
                          - 'null'
                      suspendedAt:
                        type:
                          - string
                          - 'null'
                      invitedBy:
                        type: string
                      invitationMessage:
                        type: string
                      requestedRoleKey:
                        type: string
                      establishedBy:
                        type: string
                      establishedAt:
                        type:
                          - string
                          - 'null'
                      expiresAt:
                        type:
                          - string
                          - 'null'
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - parentEntityType
                      - parentEntityId
                      - childEntityType
                      - childEntityId
                      - relationshipType
                      - status
                      - invitationToken
                      - invitationTokenExpiresAt
                      - invitedAt
                      - acceptedAt
                      - rejectedAt
                      - suspendedAt
                      - invitedBy
                      - invitationMessage
                      - requestedRoleKey
                      - establishedBy
                      - establishedAt
                      - expiresAt
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Invitation not found.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: invitation_revoke_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /entitymanagement/v1/{entityType}/{entityId}/media:
    get:
      operationId: entitymanagement.v1.media.index
      summary: Get all media for an entity.
      tags:
        - EntityMedia
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: type
          in: query
          schema:
            type: string
        - name: active
          in: query
          schema:
            type: boolean
            default: false
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityMediaResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    post:
      operationId: entitymanagement.v1.media.store
      description: >-
        NOTE: This action handles multipart/form-data — do NOT add
        api.idempotent

        middleware to the route invoking this method.
      summary: Upload new media for an entity.
      tags:
        - EntityMedia
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/StoreEntityMediaRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      mediaType:
                        type: string
                      fileName:
                        type: string
                      fileSize:
                        type:
                          - integer
                          - 'null'
                      mimeType:
                        type:
                          - string
                          - 'null'
                      url:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      uploadedBy:
                        type:
                          - integer
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - mediaType
                      - fileName
                      - fileSize
                      - mimeType
                      - url
                      - metadata
                      - uploadedBy
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/{entityType}/{entityId}/media/{mediaId}:
    get:
      operationId: entitymanagement.v1.media.show
      summary: Get a specific media item
      tags:
        - EntityMedia
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: mediaId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      mediaType:
                        type: string
                      fileName:
                        type: string
                      fileSize:
                        type:
                          - integer
                          - 'null'
                      mimeType:
                        type:
                          - string
                          - 'null'
                      url:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      uploadedBy:
                        type:
                          - integer
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - mediaType
                      - fileName
                      - fileSize
                      - mimeType
                      - url
                      - metadata
                      - uploadedBy
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Media not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
    delete:
      operationId: entitymanagement.v1.media.destroy
      summary: Delete a media item.
      tags:
        - EntityMedia
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: mediaId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Media not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /entitymanagement/v1/{entityType}/{entityId}/avatar:
    get:
      operationId: entitymanagement.v1.media.avatar.show
      summary: Get current avatar
      tags:
        - EntityMedia
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      url:
                        type: string
                      fileName:
                        type: string
                      uploadedAt:
                        type: string
                    required:
                      - id
                      - url
                      - fileName
                      - uploadedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: No avatar found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
    post:
      operationId: entitymanagement.v1.media.avatar.store
      description: >-
        NOTE: multipart/form-data — do NOT add api.idempotent middleware to this
        route.
      summary: Upload avatar shortcut.
      tags:
        - EntityMedia
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/StoreEntityMediaRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      mediaType:
                        type: string
                      fileName:
                        type: string
                      fileSize:
                        type:
                          - integer
                          - 'null'
                      mimeType:
                        type:
                          - string
                          - 'null'
                      url:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      uploadedBy:
                        type:
                          - integer
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - mediaType
                      - fileName
                      - fileSize
                      - mimeType
                      - url
                      - metadata
                      - uploadedBy
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/{entityType}/{entityId}/logo:
    get:
      operationId: entitymanagement.v1.media.logo.show
      summary: Get current logo
      tags:
        - EntityMedia
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      url:
                        type: string
                      fileName:
                        type: string
                      uploadedAt:
                        type: string
                    required:
                      - id
                      - url
                      - fileName
                      - uploadedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: No logo found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
    post:
      operationId: entitymanagement.v1.media.logo.store
      description: >-
        NOTE: multipart/form-data — do NOT add api.idempotent middleware to this
        route.
      summary: Upload logo shortcut.
      tags:
        - EntityMedia
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/StoreEntityMediaRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      mediaType:
                        type: string
                      fileName:
                        type: string
                      fileSize:
                        type:
                          - integer
                          - 'null'
                      mimeType:
                        type:
                          - string
                          - 'null'
                      url:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      uploadedBy:
                        type:
                          - integer
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - mediaType
                      - fileName
                      - fileSize
                      - mimeType
                      - url
                      - metadata
                      - uploadedBy
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitypermissions/v1/entities/{entityType}/{entityId}/users/{userId}/grants:
    get:
      operationId: entitypermissions.v1.entities.users.grants.index
      summary: List active direct permission grants for a user
      tags:
        - EntityPermissionGrantV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PermissionGrantV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                        required:
                          - total
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: entitypermissions.v1.entities.users.grants.store
      summary: Grant a permission directly to a user
      tags:
        - EntityPermissionGrantV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantPermissionV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PermissionGrantV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitypermissions/v1/entities/{entityType}/{entityId}/users/{userId}/grants/{permissionKey}:
    delete:
      operationId: entitypermissions.v1.entities.users.grants.destroy
      summary: Revoke a direct permission grant
      tags:
        - EntityPermissionGrantV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: permissionKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      revoked:
                        type: boolean
                    required:
                      - revoked
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /entitymanagement/v1/{entityType}/{entityId}/profile:
    get:
      operationId: entitymanagement.v1.profiles.show
      summary: Get the entity's profile
      tags:
        - EntityProfile
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      scopeEntityType:
                        type:
                          - string
                          - 'null'
                      scopeEntityId:
                        type:
                          - string
                          - 'null'
                      displayName:
                        type:
                          - string
                          - 'null'
                      description:
                        type:
                          - string
                          - 'null'
                      logoPath:
                        type:
                          - string
                          - 'null'
                      avatarPath:
                        type:
                          - string
                          - 'null'
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      settings:
                        type:
                          - array
                          - 'null'
                        items: {}
                      visibilityScope:
                        type: string
                      ownerEntityType:
                        type:
                          - string
                          - 'null'
                      ownerEntityId:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - scopeEntityType
                      - scopeEntityId
                      - displayName
                      - description
                      - logoPath
                      - avatarPath
                      - metadata
                      - settings
                      - visibilityScope
                      - ownerEntityType
                      - ownerEntityId
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Profile not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Entity not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
    put:
      operationId: entitymanagement.v1.profiles.update
      summary: Update the entity's profile (PUT = full replace, PATCH = partial)
      tags:
        - EntityProfile
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntityProfileRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      scopeEntityType:
                        type:
                          - string
                          - 'null'
                      scopeEntityId:
                        type:
                          - string
                          - 'null'
                      displayName:
                        type:
                          - string
                          - 'null'
                      description:
                        type:
                          - string
                          - 'null'
                      logoPath:
                        type:
                          - string
                          - 'null'
                      avatarPath:
                        type:
                          - string
                          - 'null'
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      settings:
                        type:
                          - array
                          - 'null'
                        items: {}
                      visibilityScope:
                        type: string
                      ownerEntityType:
                        type:
                          - string
                          - 'null'
                      ownerEntityId:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - scopeEntityType
                      - scopeEntityId
                      - displayName
                      - description
                      - logoPath
                      - avatarPath
                      - metadata
                      - settings
                      - visibilityScope
                      - ownerEntityType
                      - ownerEntityId
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: entitymanagement.v1.profiles.patch
      summary: Update the entity's profile (PUT = full replace, PATCH = partial)
      tags:
        - EntityProfile
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntityProfileRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      entityType:
                        type: string
                      entityId:
                        type: string
                      scopeEntityType:
                        type:
                          - string
                          - 'null'
                      scopeEntityId:
                        type:
                          - string
                          - 'null'
                      displayName:
                        type:
                          - string
                          - 'null'
                      description:
                        type:
                          - string
                          - 'null'
                      logoPath:
                        type:
                          - string
                          - 'null'
                      avatarPath:
                        type:
                          - string
                          - 'null'
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      settings:
                        type:
                          - array
                          - 'null'
                        items: {}
                      visibilityScope:
                        type: string
                      ownerEntityType:
                        type:
                          - string
                          - 'null'
                      ownerEntityId:
                        type:
                          - string
                          - 'null'
                      isActive:
                        type: boolean
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - entityType
                      - entityId
                      - scopeEntityType
                      - scopeEntityId
                      - displayName
                      - description
                      - logoPath
                      - avatarPath
                      - metadata
                      - settings
                      - visibilityScope
                      - ownerEntityType
                      - ownerEntityId
                      - isActive
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/{entityType}/{entityId}/profile/summary:
    get:
      operationId: entitymanagement.v1.profiles.summary
      summary: Get complete profile summary with all related data
      tags:
        - EntityProfile
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      entityType:
                        type: string
                      entityId:
                        type: string
                      name:
                        type: string
                      displayName:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      profile:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: integer
                          entityType:
                            type: string
                          entityId:
                            type: string
                          scopeEntityType:
                            type:
                              - string
                              - 'null'
                          scopeEntityId:
                            type:
                              - string
                              - 'null'
                          displayName:
                            type:
                              - string
                              - 'null'
                          description:
                            type:
                              - string
                              - 'null'
                          logoPath:
                            type:
                              - string
                              - 'null'
                          avatarPath:
                            type:
                              - string
                              - 'null'
                          metadata:
                            type:
                              - array
                              - 'null'
                            items: {}
                          settings:
                            type:
                              - array
                              - 'null'
                            items: {}
                          visibilityScope:
                            type: string
                          ownerEntityType:
                            type:
                              - string
                              - 'null'
                          ownerEntityId:
                            type:
                              - string
                              - 'null'
                          isActive:
                            type: boolean
                          createdAt:
                            type:
                              - string
                              - 'null'
                          updatedAt:
                            type:
                              - string
                              - 'null'
                        required:
                          - id
                          - entityType
                          - entityId
                          - scopeEntityType
                          - scopeEntityId
                          - displayName
                          - description
                          - logoPath
                          - avatarPath
                          - metadata
                          - settings
                          - visibilityScope
                          - ownerEntityType
                          - ownerEntityId
                          - isActive
                          - createdAt
                          - updatedAt
                      primaryAddress:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: string
                          entityType:
                            type: string
                          entityId:
                            type: string
                          addressType:
                            type: string
                          label:
                            type:
                              - string
                              - 'null'
                          addressLine1:
                            type:
                              - string
                              - 'null'
                          addressLine2:
                            type:
                              - string
                              - 'null'
                          city:
                            type:
                              - string
                              - 'null'
                          stateProvince:
                            type:
                              - string
                              - 'null'
                          postalCode:
                            type:
                              - string
                              - 'null'
                          countryCode:
                            type:
                              - string
                              - 'null'
                          isPrimary:
                            type: boolean
                          isActive:
                            type: boolean
                          createdAt:
                            type:
                              - string
                              - 'null'
                          updatedAt:
                            type:
                              - string
                              - 'null'
                        required:
                          - id
                          - entityType
                          - entityId
                          - addressType
                          - label
                          - addressLine1
                          - addressLine2
                          - city
                          - stateProvince
                          - postalCode
                          - countryCode
                          - isPrimary
                          - isActive
                          - createdAt
                          - updatedAt
                      addresses:
                        type: array
                        items:
                          $ref: '#/components/schemas/EntityAddressResource'
                      addressesCount:
                        type: integer
                      contacts:
                        type: array
                        items:
                          $ref: '#/components/schemas/EntityContactResource'
                      contactsCount:
                        type: integer
                      avatar:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: integer
                          url:
                            type: string
                          fileName:
                            type: string
                        required:
                          - id
                          - url
                          - fileName
                      logo:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: integer
                          url:
                            type: string
                          fileName:
                            type: string
                        required:
                          - id
                          - url
                          - fileName
                      media:
                        type: array
                        items:
                          $ref: '#/components/schemas/EntityMediaResource'
                      mediaCount:
                        type: integer
                      groupType:
                        type: string
                      memberCount:
                        type: integer
                      projectType:
                        type: string
                      status:
                        type: string
                      priority:
                        type: string
                      assignedUserCount:
                        type: integer
                      assignedGroupCount:
                        type: integer
                    required:
                      - entityType
                      - entityId
                      - name
                      - displayName
                      - description
                      - profile
                      - primaryAddress
                      - addresses
                      - addressesCount
                      - contacts
                      - contactsCount
                      - avatar
                      - logo
                      - media
                      - mediaCount
                      - groupType
                      - memberCount
                      - projectType
                      - status
                      - priority
                      - assignedUserCount
                      - assignedGroupCount
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Entity not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /entitypermissions/v1/entities/{entityType}/{entityId}/users/{userId}/roles:
    get:
      operationId: entitypermissions.v1.entities.users.roles.index
      summary: List role assignments for a user on an entity
      tags:
        - EntityRoleAssignmentV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RoleAssignmentV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                        required:
                          - total
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: entitypermissions.v1.entities.users.roles.store
      summary: Assign a role to a user on an entity
      tags:
        - EntityRoleAssignmentV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignRoleV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RoleAssignmentV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitypermissions/v1/entities/{entityType}/{entityId}/users/{userId}/roles/{roleKey}:
    delete:
      operationId: entitypermissions.v1.entities.users.roles.destroy
      summary: Revoke a role assignment from a user
      tags:
        - EntityRoleAssignmentV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: integer
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: roleKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      revoked:
                        type: boolean
                    required:
                      - revoked
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /entitymanagement/v1/groups:
    get:
      operationId: entitymanagement.v1.groups.index
      description: |-
        User-scoping: only returns groups where the user has an active member,
        owner, or admin relationship.
      summary: List groups accessible by the authenticated user.
      tags:
        - Group
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: entitymanagement.v1.groups.store
      summary: Create a new group.
      tags:
        - Group
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreGroupRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      groupType:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      isActive:
                        type: boolean
                      createdBy:
                        type: integer
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - groupType
                      - metadata
                      - isActive
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/groups/{group}:
    get:
      operationId: entitymanagement.v1.groups.show
      summary: Show a single group.
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      groupType:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      isActive:
                        type: boolean
                      createdBy:
                        type: integer
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      memberCount:
                        type: integer
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - groupType
                      - metadata
                      - isActive
                      - createdBy
                      - createdAt
                      - updatedAt
                      - memberCount
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: entitymanagement.v1.groups.update
      summary: Update a group (PUT = full replace, PATCH = partial).
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      groupType:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      isActive:
                        type: boolean
                      createdBy:
                        type: integer
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - groupType
                      - metadata
                      - isActive
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: entitymanagement.v1.groups.patch
      summary: Update a group (PUT = full replace, PATCH = partial).
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      groupType:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      isActive:
                        type: boolean
                      createdBy:
                        type: integer
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - groupType
                      - metadata
                      - isActive
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: entitymanagement.v1.groups.destroy
      summary: Deactivate a group (sets is_active = false; no cascade delete).
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /entitymanagement/v1/groups/{group}/members:
    get:
      operationId: entitymanagement.v1.groups.members.index
      summary: List members of a group (active + pending + suspended).
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        membershipId:
                          type: string
                        childEntityType:
                          type: string
                        childEntityId:
                          type: string
                        membershipStatus:
                          type: string
                        invitedAt:
                          type: string
                        acceptedAt:
                          type: string
                        displayName:
                          type:
                            - string
                            - 'null'
                        email:
                          type: 'null'
                      required:
                        - membershipId
                        - childEntityType
                        - childEntityId
                        - membershipStatus
                        - invitedAt
                        - acceptedAt
                        - displayName
                        - email
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: entitymanagement.v1.groups.members.store
      summary: Add a member to a group.
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddGroupMemberRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Member added successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/groups/{group}/members/{userId}:
    delete:
      operationId: entitymanagement.v1.groups.members.destroy
      summary: Remove a member from a group.
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: entitymanagement.v1.groups.members.update-role
      summary: Update a member's role on a group.
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupMemberRoleRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Member role updated successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/groups/{group}/members/{userId}/permissions:
    get:
      operationId: entitymanagement.v1.groups.members.permissions.index
      summary: Get a member's permissions on a group.
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      userId:
                        type: integer
                      groupId:
                        type: string
                      roles:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                            type:
                              type: string
                            assignedAt:
                              type: string
                          required:
                            - key
                            - type
                            - assignedAt
                      permissions:
                        type: array
                        items:
                          type: string
                      permissionCount:
                        type: integer
                    required:
                      - userId
                      - groupId
                      - roles
                      - permissions
                      - permissionCount
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: entitymanagement.v1.groups.members.permissions.store
      summary: Grant a specific permission to a group member.
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantMemberPermissionRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Permission granted successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/groups/{group}/members/{userId}/permissions/{permission}:
    delete:
      operationId: entitymanagement.v1.groups.members.permissions.destroy
      summary: Revoke a specific permission from a group member.
      tags:
        - Group
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: permission
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        enum:
                          - Permission revoked successfully.
                          - Permission not found.
                      revoked:
                        type: boolean
                    required:
                      - message
                      - revoked
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /cases/v1:
    delete:
      operationId: cases.v1.bulk-destroy
      description: |-
        DELETE cases/v1?ids[]=uuid1&ids[]=uuid2

        Atomic: all deletions happen in a single transaction. If any item fails
        authorization or visibility, the whole batch is rolled back.

        Returns 200 with the list of deleted IDs on success.
      summary: Bulk soft-delete cases by ID
      tags:
        - LegalCase
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: array
                        items:
                          type: string
                    required:
                      - deleted
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_failed
                      message:
                        type: string
                        const: The ids field is required.
                      details:
                        type: object
                        properties:
                          ids:
                            type: array
                            prefixItems:
                              - type: string
                                const: At least one ID is required.
                            minItems: 1
                            maxItems: 1
                            additionalItems: false
                        required:
                          - ids
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    get:
      operationId: cases.v1.index
      description: |-
        Two-tier authorization:
          1. Tenant-scope `cases.list` capability gates access to the endpoint.
          2. Layer-1 visibility filter restricts the returned set to cases that
             have a visibility-scope assignment reachable from the current
             operating scope (X-Scope header).
      summary: List all cases visible to the authenticated user in the active scope
      tags:
        - LegalCase
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LegalCaseListResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: cases.v1.store
      description: >-
        Runs in a DB transaction so case creation and role assignments are
        atomic.

        If any role assignment fails the entire operation rolls back.


        Returns 201 Created + Location header pointing to the new resource.
      summary: Create a new case and process internal team assignments
      tags:
        - LegalCase
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreCaseRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                        description: Identity
                      caseIdDisplay:
                        type: string
                      caseType:
                        type: string
                      status:
                        type: string
                        description: Status
                      clientId:
                        type: string
                        description: Client link
                      client:
                        anyOf:
                          - type: object
                            properties:
                              id:
                                type: string
                              type:
                                type: string
                              displayName:
                                type: string
                              countryCode:
                                type: string
                              registrationNumber:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  Company fields — always declared; null when
                                  client is a person
                              companySnapshot:
                                anyOf:
                                  - type: object
                                    properties:
                                      registrationNumber:
                                        type: string
                                      countryCode:
                                        type: string
                                      country:
                                        type:
                                          - string
                                          - 'null'
                                      vatNumber:
                                        type:
                                          - string
                                          - 'null'
                                      name:
                                        type: string
                                      tradingName:
                                        type:
                                          - string
                                          - 'null'
                                      status:
                                        type: string
                                      statusCode:
                                        type:
                                          - string
                                          - 'null'
                                      legalForm:
                                        type:
                                          - string
                                          - 'null'
                                      legalFormCode:
                                        type:
                                          - string
                                          - 'null'
                                      registrationDate:
                                        type: string
                                      incorporationDate:
                                        type: string
                                      dissolutionDate:
                                        type: string
                                      address:
                                        type:
                                          - object
                                          - 'null'
                                        properties:
                                          street:
                                            type:
                                              - string
                                              - 'null'
                                          street2:
                                            type:
                                              - string
                                              - 'null'
                                          postalCode:
                                            type:
                                              - string
                                              - 'null'
                                          city:
                                            type:
                                              - string
                                              - 'null'
                                          region:
                                            type:
                                              - string
                                              - 'null'
                                          countryCode:
                                            type:
                                              - string
                                              - 'null'
                                          country:
                                            type:
                                              - string
                                              - 'null'
                                        required:
                                          - street
                                          - street2
                                          - postalCode
                                          - city
                                          - region
                                          - countryCode
                                          - country
                                      postalAddress:
                                        type:
                                          - object
                                          - 'null'
                                        properties:
                                          street:
                                            type:
                                              - string
                                              - 'null'
                                          street2:
                                            type:
                                              - string
                                              - 'null'
                                          postalCode:
                                            type:
                                              - string
                                              - 'null'
                                          city:
                                            type:
                                              - string
                                              - 'null'
                                          region:
                                            type:
                                              - string
                                              - 'null'
                                          countryCode:
                                            type:
                                              - string
                                              - 'null'
                                          country:
                                            type:
                                              - string
                                              - 'null'
                                        required:
                                          - street
                                          - street2
                                          - postalCode
                                          - city
                                          - region
                                          - countryCode
                                          - country
                                      industryCode:
                                        type:
                                          - string
                                          - 'null'
                                      industryDescription:
                                        type:
                                          - string
                                          - 'null'
                                      naceCode:
                                        type:
                                          - string
                                          - 'null'
                                      numberOfEmployees:
                                        type:
                                          - integer
                                          - 'null'
                                      website:
                                        type:
                                          - string
                                          - 'null'
                                      email:
                                        type:
                                          - string
                                          - 'null'
                                      shareCapital:
                                        type:
                                          - number
                                          - 'null'
                                      capitalCurrency:
                                        type:
                                          - string
                                          - 'null'
                                      businessDescription:
                                        type:
                                          - string
                                          - 'null'
                                      sectorCode:
                                        type:
                                          - string
                                          - 'null'
                                      sectorDescription:
                                        type:
                                          - string
                                          - 'null'
                                      isGroupMember:
                                        type:
                                          - boolean
                                          - 'null'
                                      registrySource:
                                        type: string
                                      fetchedAt:
                                        type: string
                                      sourceUpdatedAt:
                                        type: string
                                      contacts:
                                        type: array
                                        description: >-
                                          rawData and rawResponseMeta are
                                          intentionally excluded.

                                          contacts included: type+value only (no
                                          rawData from sub-DTO).
                                        items: {}
                                      schemaVersion:
                                        type: integer
                                    required:
                                      - registrationNumber
                                      - countryCode
                                      - country
                                      - vatNumber
                                      - name
                                      - tradingName
                                      - status
                                      - statusCode
                                      - legalForm
                                      - legalFormCode
                                      - registrationDate
                                      - incorporationDate
                                      - dissolutionDate
                                      - address
                                      - postalAddress
                                      - industryCode
                                      - industryDescription
                                      - naceCode
                                      - numberOfEmployees
                                      - website
                                      - email
                                      - shareCapital
                                      - capitalCurrency
                                      - businessDescription
                                      - sectorCode
                                      - sectorDescription
                                      - isGroupMember
                                      - registrySource
                                      - fetchedAt
                                      - sourceUpdatedAt
                                      - contacts
                                      - schemaVersion
                                  - type: 'null'
                                  - type: object
                                    properties:
                                      industryCode:
                                        type:
                                          - string
                                          - 'null'
                                      industryDescription:
                                        type:
                                          - string
                                          - 'null'
                                    required:
                                      - industryCode
                                      - industryDescription
                              nationalIdLast4:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  Person fields — always declared; null when
                                  client is a company.

                                  national_id intentionally omitted (full value
                                  requires a dedicated endpoint + audit log).
                              dateOfBirth:
                                type:
                                  - string
                                  - 'null'
                              personSnapshot:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  name:
                                    type: string
                                  countryCode:
                                    type: string
                                  nationalIdLast4:
                                    type:
                                      - string
                                      - 'null'
                                  dateOfBirth:
                                    type:
                                      - string
                                      - 'null'
                                  address:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - name
                                  - countryCode
                                  - nationalIdLast4
                                  - dateOfBirth
                                  - address
                              status:
                                type: string
                                description: Status
                              onboardedAt:
                                type: string
                              riskClassification:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  AML summary (read-only, set by compliance
                                  systems)
                              cddLevel:
                                type:
                                  - string
                                  - 'null'
                              pepStatus:
                                type: string
                              sanctionsStatus:
                                type: string
                              amlLastReviewedAt:
                                type:
                                  - string
                                  - 'null'
                              amlNextReviewDueAt:
                                type:
                                  - string
                                  - 'null'
                              conflictCheckStatus:
                                type: string
                                description: Conflict check
                              conflictCheckedAt:
                                type:
                                  - string
                                  - 'null'
                              conflictCheckNotes:
                                type:
                                  - string
                                  - 'null'
                              engagementType:
                                type:
                                  - string
                                  - 'null'
                                description: Engagement
                              taxResidenceCountryCode:
                                type:
                                  - string
                                  - 'null'
                                description: Tax / financial
                              vatNumber:
                                type:
                                  - string
                                  - 'null'
                              lei:
                                type:
                                  - string
                                  - 'null'
                              preferredLanguage:
                                type:
                                  - string
                                  - 'null'
                                description: Comms
                              notes:
                                type:
                                  - string
                                  - 'null'
                                description: Freeform
                              tags:
                                type:
                                  - array
                                  - 'null'
                                items: {}
                              lastSyncedAt:
                                type:
                                  - string
                                  - 'null'
                                description: Meta
                              createdBy:
                                type:
                                  - string
                                  - 'null'
                              createdAt:
                                type:
                                  - string
                                  - 'null'
                              updatedAt:
                                type:
                                  - string
                                  - 'null'
                              registryId:
                                type:
                                  - integer
                                  - 'null'
                                description: Entity chain registry ID
                            required:
                              - id
                              - type
                              - displayName
                              - countryCode
                              - registrationNumber
                              - companySnapshot
                              - nationalIdLast4
                              - dateOfBirth
                              - personSnapshot
                              - status
                              - onboardedAt
                              - riskClassification
                              - cddLevel
                              - pepStatus
                              - sanctionsStatus
                              - amlLastReviewedAt
                              - amlNextReviewDueAt
                              - conflictCheckStatus
                              - conflictCheckedAt
                              - conflictCheckNotes
                              - engagementType
                              - taxResidenceCountryCode
                              - vatNumber
                              - lei
                              - preferredLanguage
                              - notes
                              - tags
                              - lastSyncedAt
                              - createdBy
                              - createdAt
                              - updatedAt
                              - registryId
                          - type: object
                      openedAt:
                        type: string
                        description: Dates
                      closedAt:
                        type: string
                      targetCompletionDate:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                        description: Freeform
                      notes:
                        type:
                          - string
                          - 'null'
                      tags:
                        type:
                          - array
                          - 'null'
                        items: {}
                      team:
                        type:
                          - object
                          - 'null'
                        description: >-
                          Team — resolved from entity_role_assignments
                          (suppressed on list context)
                        properties:
                          leadAttorney:
                            type: string
                          caseManager:
                            type: string
                          stakeholders:
                            type: array
                            items:
                              type: string
                        required:
                          - leadAttorney
                          - caseManager
                          - stakeholders
                      createdBy:
                        type:
                          - string
                          - 'null'
                        description: Audit / meta
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      registryId:
                        type:
                          - integer
                          - 'null'
                        description: Entity chain anchor
                    required:
                      - id
                      - name
                      - caseIdDisplay
                      - caseType
                      - status
                      - clientId
                      - client
                      - openedAt
                      - closedAt
                      - targetCompletionDate
                      - description
                      - notes
                      - tags
                      - team
                      - createdBy
                      - createdAt
                      - updatedAt
                      - registryId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /cases/v1/{case}:
    get:
      operationId: cases.v1.show
      description: |-
        Two-layer check:
          1. Layer 1 visibility — the case must be visible from the current
             operating scope. Returns 404 (not 403) on miss to avoid leaking
             that the case exists.
          2. Layer 3 permission — caller must hold a case role granting
             case.view (lead_attorney, case_manager, stakeholder, external_*).
      summary: Show a single case with its client
      tags:
        - LegalCase
      parameters:
        - name: case
          in: path
          required: true
          description: The case ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                        description: Identity
                      caseIdDisplay:
                        type: string
                      caseType:
                        type: string
                      status:
                        type: string
                        description: Status
                      clientId:
                        type: string
                        description: Client link
                      client:
                        anyOf:
                          - type: object
                            properties:
                              id:
                                type: string
                              type:
                                type: string
                              displayName:
                                type: string
                              countryCode:
                                type: string
                              registrationNumber:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  Company fields — always declared; null when
                                  client is a person
                              companySnapshot:
                                anyOf:
                                  - type: object
                                    properties:
                                      registrationNumber:
                                        type: string
                                      countryCode:
                                        type: string
                                      country:
                                        type:
                                          - string
                                          - 'null'
                                      vatNumber:
                                        type:
                                          - string
                                          - 'null'
                                      name:
                                        type: string
                                      tradingName:
                                        type:
                                          - string
                                          - 'null'
                                      status:
                                        type: string
                                      statusCode:
                                        type:
                                          - string
                                          - 'null'
                                      legalForm:
                                        type:
                                          - string
                                          - 'null'
                                      legalFormCode:
                                        type:
                                          - string
                                          - 'null'
                                      registrationDate:
                                        type: string
                                      incorporationDate:
                                        type: string
                                      dissolutionDate:
                                        type: string
                                      address:
                                        type:
                                          - object
                                          - 'null'
                                        properties:
                                          street:
                                            type:
                                              - string
                                              - 'null'
                                          street2:
                                            type:
                                              - string
                                              - 'null'
                                          postalCode:
                                            type:
                                              - string
                                              - 'null'
                                          city:
                                            type:
                                              - string
                                              - 'null'
                                          region:
                                            type:
                                              - string
                                              - 'null'
                                          countryCode:
                                            type:
                                              - string
                                              - 'null'
                                          country:
                                            type:
                                              - string
                                              - 'null'
                                        required:
                                          - street
                                          - street2
                                          - postalCode
                                          - city
                                          - region
                                          - countryCode
                                          - country
                                      postalAddress:
                                        type:
                                          - object
                                          - 'null'
                                        properties:
                                          street:
                                            type:
                                              - string
                                              - 'null'
                                          street2:
                                            type:
                                              - string
                                              - 'null'
                                          postalCode:
                                            type:
                                              - string
                                              - 'null'
                                          city:
                                            type:
                                              - string
                                              - 'null'
                                          region:
                                            type:
                                              - string
                                              - 'null'
                                          countryCode:
                                            type:
                                              - string
                                              - 'null'
                                          country:
                                            type:
                                              - string
                                              - 'null'
                                        required:
                                          - street
                                          - street2
                                          - postalCode
                                          - city
                                          - region
                                          - countryCode
                                          - country
                                      industryCode:
                                        type:
                                          - string
                                          - 'null'
                                      industryDescription:
                                        type:
                                          - string
                                          - 'null'
                                      naceCode:
                                        type:
                                          - string
                                          - 'null'
                                      numberOfEmployees:
                                        type:
                                          - integer
                                          - 'null'
                                      website:
                                        type:
                                          - string
                                          - 'null'
                                      email:
                                        type:
                                          - string
                                          - 'null'
                                      shareCapital:
                                        type:
                                          - number
                                          - 'null'
                                      capitalCurrency:
                                        type:
                                          - string
                                          - 'null'
                                      businessDescription:
                                        type:
                                          - string
                                          - 'null'
                                      sectorCode:
                                        type:
                                          - string
                                          - 'null'
                                      sectorDescription:
                                        type:
                                          - string
                                          - 'null'
                                      isGroupMember:
                                        type:
                                          - boolean
                                          - 'null'
                                      registrySource:
                                        type: string
                                      fetchedAt:
                                        type: string
                                      sourceUpdatedAt:
                                        type: string
                                      contacts:
                                        type: array
                                        description: >-
                                          rawData and rawResponseMeta are
                                          intentionally excluded.

                                          contacts included: type+value only (no
                                          rawData from sub-DTO).
                                        items: {}
                                      schemaVersion:
                                        type: integer
                                    required:
                                      - registrationNumber
                                      - countryCode
                                      - country
                                      - vatNumber
                                      - name
                                      - tradingName
                                      - status
                                      - statusCode
                                      - legalForm
                                      - legalFormCode
                                      - registrationDate
                                      - incorporationDate
                                      - dissolutionDate
                                      - address
                                      - postalAddress
                                      - industryCode
                                      - industryDescription
                                      - naceCode
                                      - numberOfEmployees
                                      - website
                                      - email
                                      - shareCapital
                                      - capitalCurrency
                                      - businessDescription
                                      - sectorCode
                                      - sectorDescription
                                      - isGroupMember
                                      - registrySource
                                      - fetchedAt
                                      - sourceUpdatedAt
                                      - contacts
                                      - schemaVersion
                                  - type: 'null'
                                  - type: object
                                    properties:
                                      industryCode:
                                        type:
                                          - string
                                          - 'null'
                                      industryDescription:
                                        type:
                                          - string
                                          - 'null'
                                    required:
                                      - industryCode
                                      - industryDescription
                              nationalIdLast4:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  Person fields — always declared; null when
                                  client is a company.

                                  national_id intentionally omitted (full value
                                  requires a dedicated endpoint + audit log).
                              dateOfBirth:
                                type:
                                  - string
                                  - 'null'
                              personSnapshot:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  name:
                                    type: string
                                  countryCode:
                                    type: string
                                  nationalIdLast4:
                                    type:
                                      - string
                                      - 'null'
                                  dateOfBirth:
                                    type:
                                      - string
                                      - 'null'
                                  address:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - name
                                  - countryCode
                                  - nationalIdLast4
                                  - dateOfBirth
                                  - address
                              status:
                                type: string
                                description: Status
                              onboardedAt:
                                type: string
                              riskClassification:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  AML summary (read-only, set by compliance
                                  systems)
                              cddLevel:
                                type:
                                  - string
                                  - 'null'
                              pepStatus:
                                type: string
                              sanctionsStatus:
                                type: string
                              amlLastReviewedAt:
                                type:
                                  - string
                                  - 'null'
                              amlNextReviewDueAt:
                                type:
                                  - string
                                  - 'null'
                              conflictCheckStatus:
                                type: string
                                description: Conflict check
                              conflictCheckedAt:
                                type:
                                  - string
                                  - 'null'
                              conflictCheckNotes:
                                type:
                                  - string
                                  - 'null'
                              engagementType:
                                type:
                                  - string
                                  - 'null'
                                description: Engagement
                              taxResidenceCountryCode:
                                type:
                                  - string
                                  - 'null'
                                description: Tax / financial
                              vatNumber:
                                type:
                                  - string
                                  - 'null'
                              lei:
                                type:
                                  - string
                                  - 'null'
                              preferredLanguage:
                                type:
                                  - string
                                  - 'null'
                                description: Comms
                              notes:
                                type:
                                  - string
                                  - 'null'
                                description: Freeform
                              tags:
                                type:
                                  - array
                                  - 'null'
                                items: {}
                              lastSyncedAt:
                                type:
                                  - string
                                  - 'null'
                                description: Meta
                              createdBy:
                                type:
                                  - string
                                  - 'null'
                              createdAt:
                                type:
                                  - string
                                  - 'null'
                              updatedAt:
                                type:
                                  - string
                                  - 'null'
                              registryId:
                                type:
                                  - integer
                                  - 'null'
                                description: Entity chain registry ID
                            required:
                              - id
                              - type
                              - displayName
                              - countryCode
                              - registrationNumber
                              - companySnapshot
                              - nationalIdLast4
                              - dateOfBirth
                              - personSnapshot
                              - status
                              - onboardedAt
                              - riskClassification
                              - cddLevel
                              - pepStatus
                              - sanctionsStatus
                              - amlLastReviewedAt
                              - amlNextReviewDueAt
                              - conflictCheckStatus
                              - conflictCheckedAt
                              - conflictCheckNotes
                              - engagementType
                              - taxResidenceCountryCode
                              - vatNumber
                              - lei
                              - preferredLanguage
                              - notes
                              - tags
                              - lastSyncedAt
                              - createdBy
                              - createdAt
                              - updatedAt
                              - registryId
                          - type: object
                      openedAt:
                        type: string
                        description: Dates
                      closedAt:
                        type: string
                      targetCompletionDate:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                        description: Freeform
                      notes:
                        type:
                          - string
                          - 'null'
                      tags:
                        type:
                          - array
                          - 'null'
                        items: {}
                      team:
                        type:
                          - object
                          - 'null'
                        description: >-
                          Team — resolved from entity_role_assignments
                          (suppressed on list context)
                        properties:
                          leadAttorney:
                            type: string
                          caseManager:
                            type: string
                          stakeholders:
                            type: array
                            items:
                              type: string
                        required:
                          - leadAttorney
                          - caseManager
                          - stakeholders
                      createdBy:
                        type:
                          - string
                          - 'null'
                        description: Audit / meta
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      registryId:
                        type:
                          - integer
                          - 'null'
                        description: Entity chain anchor
                    required:
                      - id
                      - name
                      - caseIdDisplay
                      - caseType
                      - status
                      - clientId
                      - client
                      - openedAt
                      - closedAt
                      - targetCompletionDate
                      - description
                      - notes
                      - tags
                      - team
                      - createdBy
                      - createdAt
                      - updatedAt
                      - registryId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: cases.v1.update
      description: |-
        Supports both PUT (full replace) and PATCH (partial update).
        PATCH is the default — `UpdateCaseRequest` uses `sometimes` throughout.
      summary: Update an existing case
      tags:
        - LegalCase
      parameters:
        - name: case
          in: path
          required: true
          description: The case ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCaseRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                        description: Identity
                      caseIdDisplay:
                        type: string
                      caseType:
                        type: string
                      status:
                        type: string
                        description: Status
                      clientId:
                        type: string
                        description: Client link
                      client:
                        anyOf:
                          - type: object
                            properties:
                              id:
                                type: string
                              type:
                                type: string
                              displayName:
                                type: string
                              countryCode:
                                type: string
                              registrationNumber:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  Company fields — always declared; null when
                                  client is a person
                              companySnapshot:
                                anyOf:
                                  - type: object
                                    properties:
                                      registrationNumber:
                                        type: string
                                      countryCode:
                                        type: string
                                      country:
                                        type:
                                          - string
                                          - 'null'
                                      vatNumber:
                                        type:
                                          - string
                                          - 'null'
                                      name:
                                        type: string
                                      tradingName:
                                        type:
                                          - string
                                          - 'null'
                                      status:
                                        type: string
                                      statusCode:
                                        type:
                                          - string
                                          - 'null'
                                      legalForm:
                                        type:
                                          - string
                                          - 'null'
                                      legalFormCode:
                                        type:
                                          - string
                                          - 'null'
                                      registrationDate:
                                        type: string
                                      incorporationDate:
                                        type: string
                                      dissolutionDate:
                                        type: string
                                      address:
                                        type:
                                          - object
                                          - 'null'
                                        properties:
                                          street:
                                            type:
                                              - string
                                              - 'null'
                                          street2:
                                            type:
                                              - string
                                              - 'null'
                                          postalCode:
                                            type:
                                              - string
                                              - 'null'
                                          city:
                                            type:
                                              - string
                                              - 'null'
                                          region:
                                            type:
                                              - string
                                              - 'null'
                                          countryCode:
                                            type:
                                              - string
                                              - 'null'
                                          country:
                                            type:
                                              - string
                                              - 'null'
                                        required:
                                          - street
                                          - street2
                                          - postalCode
                                          - city
                                          - region
                                          - countryCode
                                          - country
                                      postalAddress:
                                        type:
                                          - object
                                          - 'null'
                                        properties:
                                          street:
                                            type:
                                              - string
                                              - 'null'
                                          street2:
                                            type:
                                              - string
                                              - 'null'
                                          postalCode:
                                            type:
                                              - string
                                              - 'null'
                                          city:
                                            type:
                                              - string
                                              - 'null'
                                          region:
                                            type:
                                              - string
                                              - 'null'
                                          countryCode:
                                            type:
                                              - string
                                              - 'null'
                                          country:
                                            type:
                                              - string
                                              - 'null'
                                        required:
                                          - street
                                          - street2
                                          - postalCode
                                          - city
                                          - region
                                          - countryCode
                                          - country
                                      industryCode:
                                        type:
                                          - string
                                          - 'null'
                                      industryDescription:
                                        type:
                                          - string
                                          - 'null'
                                      naceCode:
                                        type:
                                          - string
                                          - 'null'
                                      numberOfEmployees:
                                        type:
                                          - integer
                                          - 'null'
                                      website:
                                        type:
                                          - string
                                          - 'null'
                                      email:
                                        type:
                                          - string
                                          - 'null'
                                      shareCapital:
                                        type:
                                          - number
                                          - 'null'
                                      capitalCurrency:
                                        type:
                                          - string
                                          - 'null'
                                      businessDescription:
                                        type:
                                          - string
                                          - 'null'
                                      sectorCode:
                                        type:
                                          - string
                                          - 'null'
                                      sectorDescription:
                                        type:
                                          - string
                                          - 'null'
                                      isGroupMember:
                                        type:
                                          - boolean
                                          - 'null'
                                      registrySource:
                                        type: string
                                      fetchedAt:
                                        type: string
                                      sourceUpdatedAt:
                                        type: string
                                      contacts:
                                        type: array
                                        description: >-
                                          rawData and rawResponseMeta are
                                          intentionally excluded.

                                          contacts included: type+value only (no
                                          rawData from sub-DTO).
                                        items: {}
                                      schemaVersion:
                                        type: integer
                                    required:
                                      - registrationNumber
                                      - countryCode
                                      - country
                                      - vatNumber
                                      - name
                                      - tradingName
                                      - status
                                      - statusCode
                                      - legalForm
                                      - legalFormCode
                                      - registrationDate
                                      - incorporationDate
                                      - dissolutionDate
                                      - address
                                      - postalAddress
                                      - industryCode
                                      - industryDescription
                                      - naceCode
                                      - numberOfEmployees
                                      - website
                                      - email
                                      - shareCapital
                                      - capitalCurrency
                                      - businessDescription
                                      - sectorCode
                                      - sectorDescription
                                      - isGroupMember
                                      - registrySource
                                      - fetchedAt
                                      - sourceUpdatedAt
                                      - contacts
                                      - schemaVersion
                                  - type: 'null'
                                  - type: object
                                    properties:
                                      industryCode:
                                        type:
                                          - string
                                          - 'null'
                                      industryDescription:
                                        type:
                                          - string
                                          - 'null'
                                    required:
                                      - industryCode
                                      - industryDescription
                              nationalIdLast4:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  Person fields — always declared; null when
                                  client is a company.

                                  national_id intentionally omitted (full value
                                  requires a dedicated endpoint + audit log).
                              dateOfBirth:
                                type:
                                  - string
                                  - 'null'
                              personSnapshot:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  name:
                                    type: string
                                  countryCode:
                                    type: string
                                  nationalIdLast4:
                                    type:
                                      - string
                                      - 'null'
                                  dateOfBirth:
                                    type:
                                      - string
                                      - 'null'
                                  address:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - name
                                  - countryCode
                                  - nationalIdLast4
                                  - dateOfBirth
                                  - address
                              status:
                                type: string
                                description: Status
                              onboardedAt:
                                type: string
                              riskClassification:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  AML summary (read-only, set by compliance
                                  systems)
                              cddLevel:
                                type:
                                  - string
                                  - 'null'
                              pepStatus:
                                type: string
                              sanctionsStatus:
                                type: string
                              amlLastReviewedAt:
                                type:
                                  - string
                                  - 'null'
                              amlNextReviewDueAt:
                                type:
                                  - string
                                  - 'null'
                              conflictCheckStatus:
                                type: string
                                description: Conflict check
                              conflictCheckedAt:
                                type:
                                  - string
                                  - 'null'
                              conflictCheckNotes:
                                type:
                                  - string
                                  - 'null'
                              engagementType:
                                type:
                                  - string
                                  - 'null'
                                description: Engagement
                              taxResidenceCountryCode:
                                type:
                                  - string
                                  - 'null'
                                description: Tax / financial
                              vatNumber:
                                type:
                                  - string
                                  - 'null'
                              lei:
                                type:
                                  - string
                                  - 'null'
                              preferredLanguage:
                                type:
                                  - string
                                  - 'null'
                                description: Comms
                              notes:
                                type:
                                  - string
                                  - 'null'
                                description: Freeform
                              tags:
                                type:
                                  - array
                                  - 'null'
                                items: {}
                              lastSyncedAt:
                                type:
                                  - string
                                  - 'null'
                                description: Meta
                              createdBy:
                                type:
                                  - string
                                  - 'null'
                              createdAt:
                                type:
                                  - string
                                  - 'null'
                              updatedAt:
                                type:
                                  - string
                                  - 'null'
                              registryId:
                                type:
                                  - integer
                                  - 'null'
                                description: Entity chain registry ID
                            required:
                              - id
                              - type
                              - displayName
                              - countryCode
                              - registrationNumber
                              - companySnapshot
                              - nationalIdLast4
                              - dateOfBirth
                              - personSnapshot
                              - status
                              - onboardedAt
                              - riskClassification
                              - cddLevel
                              - pepStatus
                              - sanctionsStatus
                              - amlLastReviewedAt
                              - amlNextReviewDueAt
                              - conflictCheckStatus
                              - conflictCheckedAt
                              - conflictCheckNotes
                              - engagementType
                              - taxResidenceCountryCode
                              - vatNumber
                              - lei
                              - preferredLanguage
                              - notes
                              - tags
                              - lastSyncedAt
                              - createdBy
                              - createdAt
                              - updatedAt
                              - registryId
                          - type: object
                      openedAt:
                        type: string
                        description: Dates
                      closedAt:
                        type: string
                      targetCompletionDate:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                        description: Freeform
                      notes:
                        type:
                          - string
                          - 'null'
                      tags:
                        type:
                          - array
                          - 'null'
                        items: {}
                      team:
                        type:
                          - object
                          - 'null'
                        description: >-
                          Team — resolved from entity_role_assignments
                          (suppressed on list context)
                        properties:
                          leadAttorney:
                            type: string
                          caseManager:
                            type: string
                          stakeholders:
                            type: array
                            items:
                              type: string
                        required:
                          - leadAttorney
                          - caseManager
                          - stakeholders
                      createdBy:
                        type:
                          - string
                          - 'null'
                        description: Audit / meta
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      registryId:
                        type:
                          - integer
                          - 'null'
                        description: Entity chain anchor
                    required:
                      - id
                      - name
                      - caseIdDisplay
                      - caseType
                      - status
                      - clientId
                      - client
                      - openedAt
                      - closedAt
                      - targetCompletionDate
                      - description
                      - notes
                      - tags
                      - team
                      - createdBy
                      - createdAt
                      - updatedAt
                      - registryId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: cases.v1.patch
      description: |-
        Supports both PUT (full replace) and PATCH (partial update).
        PATCH is the default — `UpdateCaseRequest` uses `sometimes` throughout.
      summary: Update an existing case
      tags:
        - LegalCase
      parameters:
        - name: case
          in: path
          required: true
          description: The case ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCaseRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                        description: Identity
                      caseIdDisplay:
                        type: string
                      caseType:
                        type: string
                      status:
                        type: string
                        description: Status
                      clientId:
                        type: string
                        description: Client link
                      client:
                        anyOf:
                          - type: object
                            properties:
                              id:
                                type: string
                              type:
                                type: string
                              displayName:
                                type: string
                              countryCode:
                                type: string
                              registrationNumber:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  Company fields — always declared; null when
                                  client is a person
                              companySnapshot:
                                anyOf:
                                  - type: object
                                    properties:
                                      registrationNumber:
                                        type: string
                                      countryCode:
                                        type: string
                                      country:
                                        type:
                                          - string
                                          - 'null'
                                      vatNumber:
                                        type:
                                          - string
                                          - 'null'
                                      name:
                                        type: string
                                      tradingName:
                                        type:
                                          - string
                                          - 'null'
                                      status:
                                        type: string
                                      statusCode:
                                        type:
                                          - string
                                          - 'null'
                                      legalForm:
                                        type:
                                          - string
                                          - 'null'
                                      legalFormCode:
                                        type:
                                          - string
                                          - 'null'
                                      registrationDate:
                                        type: string
                                      incorporationDate:
                                        type: string
                                      dissolutionDate:
                                        type: string
                                      address:
                                        type:
                                          - object
                                          - 'null'
                                        properties:
                                          street:
                                            type:
                                              - string
                                              - 'null'
                                          street2:
                                            type:
                                              - string
                                              - 'null'
                                          postalCode:
                                            type:
                                              - string
                                              - 'null'
                                          city:
                                            type:
                                              - string
                                              - 'null'
                                          region:
                                            type:
                                              - string
                                              - 'null'
                                          countryCode:
                                            type:
                                              - string
                                              - 'null'
                                          country:
                                            type:
                                              - string
                                              - 'null'
                                        required:
                                          - street
                                          - street2
                                          - postalCode
                                          - city
                                          - region
                                          - countryCode
                                          - country
                                      postalAddress:
                                        type:
                                          - object
                                          - 'null'
                                        properties:
                                          street:
                                            type:
                                              - string
                                              - 'null'
                                          street2:
                                            type:
                                              - string
                                              - 'null'
                                          postalCode:
                                            type:
                                              - string
                                              - 'null'
                                          city:
                                            type:
                                              - string
                                              - 'null'
                                          region:
                                            type:
                                              - string
                                              - 'null'
                                          countryCode:
                                            type:
                                              - string
                                              - 'null'
                                          country:
                                            type:
                                              - string
                                              - 'null'
                                        required:
                                          - street
                                          - street2
                                          - postalCode
                                          - city
                                          - region
                                          - countryCode
                                          - country
                                      industryCode:
                                        type:
                                          - string
                                          - 'null'
                                      industryDescription:
                                        type:
                                          - string
                                          - 'null'
                                      naceCode:
                                        type:
                                          - string
                                          - 'null'
                                      numberOfEmployees:
                                        type:
                                          - integer
                                          - 'null'
                                      website:
                                        type:
                                          - string
                                          - 'null'
                                      email:
                                        type:
                                          - string
                                          - 'null'
                                      shareCapital:
                                        type:
                                          - number
                                          - 'null'
                                      capitalCurrency:
                                        type:
                                          - string
                                          - 'null'
                                      businessDescription:
                                        type:
                                          - string
                                          - 'null'
                                      sectorCode:
                                        type:
                                          - string
                                          - 'null'
                                      sectorDescription:
                                        type:
                                          - string
                                          - 'null'
                                      isGroupMember:
                                        type:
                                          - boolean
                                          - 'null'
                                      registrySource:
                                        type: string
                                      fetchedAt:
                                        type: string
                                      sourceUpdatedAt:
                                        type: string
                                      contacts:
                                        type: array
                                        description: >-
                                          rawData and rawResponseMeta are
                                          intentionally excluded.

                                          contacts included: type+value only (no
                                          rawData from sub-DTO).
                                        items: {}
                                      schemaVersion:
                                        type: integer
                                    required:
                                      - registrationNumber
                                      - countryCode
                                      - country
                                      - vatNumber
                                      - name
                                      - tradingName
                                      - status
                                      - statusCode
                                      - legalForm
                                      - legalFormCode
                                      - registrationDate
                                      - incorporationDate
                                      - dissolutionDate
                                      - address
                                      - postalAddress
                                      - industryCode
                                      - industryDescription
                                      - naceCode
                                      - numberOfEmployees
                                      - website
                                      - email
                                      - shareCapital
                                      - capitalCurrency
                                      - businessDescription
                                      - sectorCode
                                      - sectorDescription
                                      - isGroupMember
                                      - registrySource
                                      - fetchedAt
                                      - sourceUpdatedAt
                                      - contacts
                                      - schemaVersion
                                  - type: 'null'
                                  - type: object
                                    properties:
                                      industryCode:
                                        type:
                                          - string
                                          - 'null'
                                      industryDescription:
                                        type:
                                          - string
                                          - 'null'
                                    required:
                                      - industryCode
                                      - industryDescription
                              nationalIdLast4:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  Person fields — always declared; null when
                                  client is a company.

                                  national_id intentionally omitted (full value
                                  requires a dedicated endpoint + audit log).
                              dateOfBirth:
                                type:
                                  - string
                                  - 'null'
                              personSnapshot:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  name:
                                    type: string
                                  countryCode:
                                    type: string
                                  nationalIdLast4:
                                    type:
                                      - string
                                      - 'null'
                                  dateOfBirth:
                                    type:
                                      - string
                                      - 'null'
                                  address:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - name
                                  - countryCode
                                  - nationalIdLast4
                                  - dateOfBirth
                                  - address
                              status:
                                type: string
                                description: Status
                              onboardedAt:
                                type: string
                              riskClassification:
                                type:
                                  - string
                                  - 'null'
                                description: >-
                                  AML summary (read-only, set by compliance
                                  systems)
                              cddLevel:
                                type:
                                  - string
                                  - 'null'
                              pepStatus:
                                type: string
                              sanctionsStatus:
                                type: string
                              amlLastReviewedAt:
                                type:
                                  - string
                                  - 'null'
                              amlNextReviewDueAt:
                                type:
                                  - string
                                  - 'null'
                              conflictCheckStatus:
                                type: string
                                description: Conflict check
                              conflictCheckedAt:
                                type:
                                  - string
                                  - 'null'
                              conflictCheckNotes:
                                type:
                                  - string
                                  - 'null'
                              engagementType:
                                type:
                                  - string
                                  - 'null'
                                description: Engagement
                              taxResidenceCountryCode:
                                type:
                                  - string
                                  - 'null'
                                description: Tax / financial
                              vatNumber:
                                type:
                                  - string
                                  - 'null'
                              lei:
                                type:
                                  - string
                                  - 'null'
                              preferredLanguage:
                                type:
                                  - string
                                  - 'null'
                                description: Comms
                              notes:
                                type:
                                  - string
                                  - 'null'
                                description: Freeform
                              tags:
                                type:
                                  - array
                                  - 'null'
                                items: {}
                              lastSyncedAt:
                                type:
                                  - string
                                  - 'null'
                                description: Meta
                              createdBy:
                                type:
                                  - string
                                  - 'null'
                              createdAt:
                                type:
                                  - string
                                  - 'null'
                              updatedAt:
                                type:
                                  - string
                                  - 'null'
                              registryId:
                                type:
                                  - integer
                                  - 'null'
                                description: Entity chain registry ID
                            required:
                              - id
                              - type
                              - displayName
                              - countryCode
                              - registrationNumber
                              - companySnapshot
                              - nationalIdLast4
                              - dateOfBirth
                              - personSnapshot
                              - status
                              - onboardedAt
                              - riskClassification
                              - cddLevel
                              - pepStatus
                              - sanctionsStatus
                              - amlLastReviewedAt
                              - amlNextReviewDueAt
                              - conflictCheckStatus
                              - conflictCheckedAt
                              - conflictCheckNotes
                              - engagementType
                              - taxResidenceCountryCode
                              - vatNumber
                              - lei
                              - preferredLanguage
                              - notes
                              - tags
                              - lastSyncedAt
                              - createdBy
                              - createdAt
                              - updatedAt
                              - registryId
                          - type: object
                      openedAt:
                        type: string
                        description: Dates
                      closedAt:
                        type: string
                      targetCompletionDate:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                        description: Freeform
                      notes:
                        type:
                          - string
                          - 'null'
                      tags:
                        type:
                          - array
                          - 'null'
                        items: {}
                      team:
                        type:
                          - object
                          - 'null'
                        description: >-
                          Team — resolved from entity_role_assignments
                          (suppressed on list context)
                        properties:
                          leadAttorney:
                            type: string
                          caseManager:
                            type: string
                          stakeholders:
                            type: array
                            items:
                              type: string
                        required:
                          - leadAttorney
                          - caseManager
                          - stakeholders
                      createdBy:
                        type:
                          - string
                          - 'null'
                        description: Audit / meta
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      registryId:
                        type:
                          - integer
                          - 'null'
                        description: Entity chain anchor
                    required:
                      - id
                      - name
                      - caseIdDisplay
                      - caseType
                      - status
                      - clientId
                      - client
                      - openedAt
                      - closedAt
                      - targetCompletionDate
                      - description
                      - notes
                      - tags
                      - team
                      - createdBy
                      - createdAt
                      - updatedAt
                      - registryId
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: cases.v1.destroy
      description: Returns 204 No Content on success.
      summary: Soft-delete a case
      tags:
        - LegalCase
      parameters:
        - name: case
          in: path
          required: true
          description: The case ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/mappings/bind-account:
    post:
      operationId: accounttracking.v1.mappings.bind-account
      description: |-
        Bind an account identifier to an entity.
        Returns 201 + AccountMappingV1Resource.
      summary: Bind an account identifier to an entity
      tags:
        - MappingV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindAccountV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      accountIdentifier:
                        type: string
                      entityId:
                        type: string
                      entityType:
                        type: string
                      ownershipType:
                        type: string
                      confidenceScore:
                        type: string
                      accessScope:
                        type: string
                      countryCode:
                        type: string
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - accountIdentifier
                      - entityId
                      - entityType
                      - ownershipType
                      - confidenceScore
                      - accessScope
                      - countryCode
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bind_account_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bind_account_failed
                      message:
                        type: string
                        const: Failed to create account-entity mapping
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings/auto-generate:
    post:
      operationId: accounttracking.v1.mappings.auto-generate
      description: Auto-generate mappings based on transaction history.
      summary: Auto-generate account-entity mappings from transaction history
      tags:
        - MappingV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                min_confidence:
                  type:
                    - number
                    - 'null'
                  minimum: 0.5
                  maximum: 1
                access_scope:
                  type:
                    - string
                    - 'null'
                  enum:
                    - private
                    - user
                    - group
                    - tenant
                    - global
                dry_run:
                  type:
                    - boolean
                    - 'null'
                account_identifiers:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                    maxLength: 50
                  maxItems: 100
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        enum:
                          - Auto-generation dry run completed
                          - Auto-generation completed
                      generated:
                        type: integer
                      skipped:
                        type: integer
                      suggestions:
                        type: array
                        items:
                          type: object
                          properties:
                            accountIdentifier:
                              type: string
                            entityId:
                              type: string
                            entityType:
                              type: string
                            confidence:
                              type: string
                            reason:
                              type: string
                          required:
                            - accountIdentifier
                            - entityId
                            - entityType
                            - confidence
                            - reason
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            accountIdentifier:
                              type: string
                            error:
                              type: string
                          required:
                            - accountIdentifier
                            - error
                    required:
                      - message
                      - generated
                      - skipped
                      - suggestions
                      - errors
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/mappings/bulk-import:
    post:
      operationId: accounttracking.v1.mappings.bulk-import
      description: Bulk import mappings.
      summary: Bulk import account-entity mappings
      tags:
        - MappingV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mappings:
                  type: array
                  items:
                    type: array
                    items:
                      type: string
                  minItems: 1
              required:
                - mappings
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      imported:
                        type: integer
                      updated:
                        type: integer
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            index:
                              type: string
                            data:
                              type: string
                            error:
                              type: string
                          required:
                            - index
                            - data
                            - error
                    required:
                      - imported
                      - updated
                      - errors
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bulk_import_failed
                      message:
                        type: string
                        const: Failed to import mappings
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings/stats:
    get:
      operationId: accounttracking.v1.mappings.stats
      description: Get mapping statistics for the current user.
      summary: Get mapping statistics for the current user
      tags:
        - MappingV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      total_accessible_mappings:
                        type: integer
                      active_accessible_mappings:
                        type: integer
                      mappings_by_ownership_type:
                        type: string
                      mappings_by_source:
                        type: string
                      mappings_by_scope:
                        type: string
                      high_confidence_mappings:
                        type: integer
                      manual_mappings:
                        type: integer
                      auto_generated_mappings:
                        type: integer
                      own_mappings:
                        type: integer
                    required:
                      - total_accessible_mappings
                      - active_accessible_mappings
                      - mappings_by_ownership_type
                      - mappings_by_source
                      - mappings_by_scope
                      - high_confidence_mappings
                      - manual_mappings
                      - auto_generated_mappings
                      - own_mappings
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: stats_failed
                      message:
                        type: string
                        const: Failed to get mapping stats
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings/entities/{entityType}/{entityId}/accounts:
    get:
      operationId: accounttracking.v1.mappings.entity-accounts
      description: Get accounts mapped to an entity.
      summary: List accounts mapped to an entity
      tags:
        - MappingV1
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
        - name: entityId
          in: path
          required: true
          schema:
            type: string
        - name: ownership_type
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      entityId:
                        type: string
                      entityType:
                        type: string
                      accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            accountIdentifier:
                              type: string
                            accountType:
                              type: string
                            countryCode:
                              type: string
                            ownershipType:
                              type: string
                            confidenceScore:
                              type:
                                - string
                                - 'null'
                            mappingSource:
                              type: string
                            establishedAt:
                              type: string
                              format: date-time
                          required:
                            - id
                            - accountIdentifier
                            - accountType
                            - countryCode
                            - ownershipType
                            - confidenceScore
                            - mappingSource
                            - establishedAt
                    required:
                      - entityId
                      - entityType
                      - accounts
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: entity_accounts_failed
                      message:
                        type: string
                        const: Failed to get entity accounts
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings/accounts/{accountIdentifier}/suggestions:
    get:
      operationId: accounttracking.v1.mappings.account-suggestions
      description: Get entity suggestions for an account.
      summary: Suggest entities for an account identifier
      tags:
        - MappingV1
      parameters:
        - name: accountIdentifier
          in: path
          required: true
          schema:
            type: string
        - name: accountName
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      accountIdentifier:
                        type: string
                      suggestions:
                        type: array
                        items:
                          type: object
                          properties:
                            entityId:
                              type: string
                            entityType:
                              type: string
                            entityName:
                              type: string
                            confidence:
                              type: string
                            reason:
                              type: string
                            source:
                              type: string
                          required:
                            - entityId
                            - entityType
                            - entityName
                            - confidence
                            - reason
                            - source
                    required:
                      - accountIdentifier
                      - suggestions
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: suggestions_failed
                      message:
                        type: string
                        const: Failed to get entity suggestions
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings/accounts/{accountIdentifier}/bindings:
    delete:
      operationId: accounttracking.v1.mappings.unbind-account
      description: Remove all entity bindings for an account identifier.
      summary: Remove all entity bindings for an account identifier
      tags:
        - MappingV1
      parameters:
        - name: accountIdentifier
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      accountIdentifier:
                        type: string
                      deactivatedCount:
                        type: integer
                    required:
                      - message
                      - accountIdentifier
                      - deactivatedCount
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: unbind_failed
                      message:
                        type: string
                        const: Failed to unbind account bindings
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings/transactions/{transactionId}/bind-entity:
    post:
      operationId: accounttracking.v1.mappings.bind-transaction
      description: Bind a transaction to an entity.
      summary: Bind a transaction to an entity
      tags:
        - MappingV1
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindTransactionToEntityV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Transaction successfully bound to entity
                      transactionId:
                        type: string
                      entity:
                        type: object
                        properties:
                          id:
                            type: string
                          type:
                            type: string
                          name:
                            type:
                              - string
                              - 'null'
                        required:
                          - id
                          - type
                          - name
                      mappingCreated:
                        type: boolean
                    required:
                      - message
                      - transactionId
                      - entity
                      - mappingCreated
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: bind_failed
                          message:
                            type: string
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: bind_failed
                          message:
                            type: string
                            const: Failed to bind transaction to entity
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Transaction not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bind_failed
                      message:
                        type: string
                        const: Failed to bind transaction to entity
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    delete:
      operationId: accounttracking.v1.mappings.unbind-transaction
      description: |-
        Unbind a transaction from its entity.
        Returns 204 No Content.
      summary: Unbind a transaction from its entity
      tags:
        - MappingV1
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: unbind_failed
                      message:
                        type: string
                        const: Failed to unbind transaction from entity
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Transaction not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: unbind_failed
                      message:
                        type: string
                        const: Failed to unbind transaction from entity
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings/transactions/{transactionId}/suggestions:
    get:
      operationId: accounttracking.v1.mappings.transaction-suggestions
      description: Get entity suggestions for a transaction.
      summary: Suggest entities for a transaction
      tags:
        - MappingV1
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      transactionId:
                        type: integer
                      counterpartyAccount:
                        type: string
                      counterpartyName:
                        type: string
                      suggestions:
                        type: array
                        items:
                          type: object
                          properties:
                            entityId:
                              type: string
                            entityType:
                              type: string
                            entityName:
                              type: string
                            confidence:
                              type: string
                            reason:
                              type: string
                            source:
                              type: string
                          required:
                            - entityId
                            - entityType
                            - entityName
                            - confidence
                            - reason
                            - source
                    required:
                      - transactionId
                      - counterpartyAccount
                      - counterpartyName
                      - suggestions
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Transaction not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: suggestions_failed
                      message:
                        type: string
                        const: Failed to get entity suggestions
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings:
    get:
      operationId: accounttracking.v1.mappings.index
      description: List mappings accessible to the current user.
      summary: List account-entity mappings accessible to the current user
      tags:
        - MappingV1
      parameters:
        - name: accountIdentifier
          in: query
          schema:
            type: string
        - name: entityType
          in: query
          schema:
            type: string
        - name: ownershipType
          in: query
          schema:
            type: string
        - name: accessScope
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        accountIdentifier:
                          type: string
                        entityId:
                          type: string
                        entityType:
                          type: string
                        ownershipType:
                          type: string
                        confidenceScore:
                          type: string
                        accessScope:
                          type: string
                        countryCode:
                          type: string
                        metadata:
                          type: string
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - accountIdentifier
                        - entityId
                        - entityType
                        - ownershipType
                        - confidenceScore
                        - accessScope
                        - countryCode
                        - metadata
                        - createdAt
                        - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type:
                              - object
                              - 'null'
                          currentPage:
                            type:
                              - object
                              - 'null'
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: mappings_fetch_failed
                      message:
                        type: string
                        const: Failed to retrieve mappings
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/mappings/{id}:
    get:
      operationId: accounttracking.v1.mappings.show
      description: Get a specific mapping.
      summary: Get a specific account-entity mapping
      tags:
        - MappingV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      accountIdentifier:
                        type: string
                      entityId:
                        type: string
                      entityType:
                        type: string
                      ownershipType:
                        type: string
                      confidenceScore:
                        type: string
                      accessScope:
                        type: string
                      countryCode:
                        type: string
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - accountIdentifier
                      - entityId
                      - entityType
                      - ownershipType
                      - confidenceScore
                      - accessScope
                      - countryCode
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Mapping not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    put:
      operationId: accounttracking.v1.mappings.update
      description: Update a mapping.
      summary: Update an account-entity mapping
      tags:
        - MappingV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMappingV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      accountIdentifier:
                        type: string
                      entityId:
                        type: string
                      entityType:
                        type: string
                      ownershipType:
                        type: string
                      confidenceScore:
                        type: string
                      accessScope:
                        type: string
                      countryCode:
                        type: string
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - accountIdentifier
                      - entityId
                      - entityType
                      - ownershipType
                      - confidenceScore
                      - accessScope
                      - countryCode
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Mapping not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: update_failed
                      message:
                        type: string
                        const: Failed to update mapping
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    delete:
      operationId: accounttracking.v1.mappings.destroy
      description: |-
        Delete/deactivate a mapping.
        Returns 204 No Content.
      summary: Delete/deactivate an account-entity mapping
      tags:
        - MappingV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Mapping not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: delete_failed
                      message:
                        type: string
                        const: Failed to delete mapping
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /entitypermissions/v1/me/entity-permissions:
    get:
      operationId: entitypermissions.v1.me.entity-permissions
      tags:
        - MeEntityPermissionsV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MeEntityPermissionsV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      summary: Entity permissions me
  /entitypermissions/v1/me/permissions:
    get:
      operationId: entitypermissions.v1.me.permissions
      tags:
        - MePermissionsV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: assoc array
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MePermissionsV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      summary: Permissions me
  /accounttracking/v1/merged-transactions:
    get:
      operationId: accounttracking.v1.merged-transactions
      description: |-
        Ad-hoc merged transactions, cursor-paginated.
        Requires ?accountIds[]= query parameter.
      summary: Ad-hoc merged transactions for given accounts
      tags:
        - MergedViewV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_error
                      message:
                        type: string
                        const: accountIds is required
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/merged-aggregates:
    get:
      operationId: accounttracking.v1.merged-aggregates
      description: Ad-hoc merged aggregates.
      summary: Ad-hoc merged aggregates for given accounts
      tags:
        - MergedViewV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_error
                      message:
                        type: string
                        const: accountIds is required
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/merged-counterparts:
    get:
      operationId: accounttracking.v1.merged-counterparts
      description: Ad-hoc merged counterparts.
      summary: Ad-hoc merged counterparts for given accounts
      tags:
        - MergedViewV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: validation_error
                      message:
                        type: string
                        const: accountIds is required
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/views:
    get:
      operationId: accounttracking.v1.views.index
      description: List merged account views visible to the actor.
      summary: List merged account views visible to the actor
      tags:
        - MergedViewV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        description:
                          type: string
                        defaultFromDate:
                          type: string
                        defaultToDate:
                          type: string
                        defaultBucket:
                          type: string
                        accounts:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                              name:
                                type:
                                  - string
                                  - 'null'
                              number:
                                type:
                                  - string
                                  - 'null'
                              bank:
                                type:
                                  - string
                                  - 'null'
                              position:
                                type: integer
                              colorHint:
                                type:
                                  - string
                                  - 'null'
                            required:
                              - id
                              - name
                              - number
                              - bank
                              - position
                              - colorHint
                        accountIds:
                          type: array
                          items: {}
                        isFavorite:
                          type: boolean
                        owner:
                          type:
                            - string
                            - 'null'
                        deniedAccountIds:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                              minItems: 0
                              maxItems: 0
                              additionalItems: false
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - name
                        - description
                        - defaultFromDate
                        - defaultToDate
                        - defaultBucket
                        - accounts
                        - accountIds
                        - isFavorite
                        - owner
                        - deniedAccountIds
                        - createdAt
                        - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type: integer
                          currentPage:
                            type: integer
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: accounttracking.v1.views.store
      description: |-
        Create a new merged account view.
        Returns 201 + Location header.
      summary: Create a merged account view
      tags:
        - MergedViewV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/StoreViewV1Request'
                - type: object
                  properties:
                    colorHints:
                      type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      defaultFromDate:
                        type: string
                      defaultToDate:
                        type: string
                      defaultBucket:
                        type: string
                      accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type:
                                - string
                                - 'null'
                            number:
                              type:
                                - string
                                - 'null'
                            bank:
                              type:
                                - string
                                - 'null'
                            position:
                              type: integer
                            colorHint:
                              type:
                                - string
                                - 'null'
                          required:
                            - id
                            - name
                            - number
                            - bank
                            - position
                            - colorHint
                      accountIds:
                        type: array
                        items: {}
                      isFavorite:
                        type: boolean
                      owner:
                        type:
                          - string
                          - 'null'
                      deniedAccountIds:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              type: string
                            minItems: 0
                            maxItems: 0
                            additionalItems: false
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - description
                      - defaultFromDate
                      - defaultToDate
                      - defaultBucket
                      - accounts
                      - accountIds
                      - isFavorite
                      - owner
                      - deniedAccountIds
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: scope_required
                      message:
                        type: string
                        const: Scope header required
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/views/{view}:
    get:
      operationId: accounttracking.v1.views.show
      description: Fetch a single merged account view.
      summary: Fetch a single merged account view
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      defaultFromDate:
                        type: string
                      defaultToDate:
                        type: string
                      defaultBucket:
                        type: string
                      accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type:
                                - string
                                - 'null'
                            number:
                              type:
                                - string
                                - 'null'
                            bank:
                              type:
                                - string
                                - 'null'
                            position:
                              type: integer
                            colorHint:
                              type:
                                - string
                                - 'null'
                          required:
                            - id
                            - name
                            - number
                            - bank
                            - position
                            - colorHint
                      accountIds:
                        type: array
                        items: {}
                      isFavorite:
                        type: boolean
                      owner:
                        type:
                          - string
                          - 'null'
                      deniedAccountIds:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              type: string
                            minItems: 0
                            maxItems: 0
                            additionalItems: false
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - description
                      - defaultFromDate
                      - defaultToDate
                      - defaultBucket
                      - accounts
                      - accountIds
                      - isFavorite
                      - owner
                      - deniedAccountIds
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: accounttracking.v1.views.update
      description: Update a merged account view.
      summary: PUT/PATCH accounttracking/v1/views/{view} — update a merged account view
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateViewV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      defaultFromDate:
                        type: string
                      defaultToDate:
                        type: string
                      defaultBucket:
                        type: string
                      accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type:
                                - string
                                - 'null'
                            number:
                              type:
                                - string
                                - 'null'
                            bank:
                              type:
                                - string
                                - 'null'
                            position:
                              type: integer
                            colorHint:
                              type:
                                - string
                                - 'null'
                          required:
                            - id
                            - name
                            - number
                            - bank
                            - position
                            - colorHint
                      accountIds:
                        type: array
                        items: {}
                      isFavorite:
                        type: boolean
                      owner:
                        type:
                          - string
                          - 'null'
                      deniedAccountIds:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              type: string
                            minItems: 0
                            maxItems: 0
                            additionalItems: false
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - description
                      - defaultFromDate
                      - defaultToDate
                      - defaultBucket
                      - accounts
                      - accountIds
                      - isFavorite
                      - owner
                      - deniedAccountIds
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: accounttracking.v1.views.patch
      description: Update a merged account view.
      summary: PUT/PATCH accounttracking/v1/views/{view} — update a merged account view
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateViewV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      defaultFromDate:
                        type: string
                      defaultToDate:
                        type: string
                      defaultBucket:
                        type: string
                      accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type:
                                - string
                                - 'null'
                            number:
                              type:
                                - string
                                - 'null'
                            bank:
                              type:
                                - string
                                - 'null'
                            position:
                              type: integer
                            colorHint:
                              type:
                                - string
                                - 'null'
                          required:
                            - id
                            - name
                            - number
                            - bank
                            - position
                            - colorHint
                      accountIds:
                        type: array
                        items: {}
                      isFavorite:
                        type: boolean
                      owner:
                        type:
                          - string
                          - 'null'
                      deniedAccountIds:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              type: string
                            minItems: 0
                            maxItems: 0
                            additionalItems: false
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - description
                      - defaultFromDate
                      - defaultToDate
                      - defaultBucket
                      - accounts
                      - accountIds
                      - isFavorite
                      - owner
                      - deniedAccountIds
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: accounttracking.v1.views.destroy
      description: |-
        Delete a merged account view.
        Returns 204 No Content.
      summary: Delete a merged account view
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/views/{view}/transactions:
    get:
      operationId: accounttracking.v1.views.transactions
      description: Get transactions for a saved view. Cursor-paginated.
      summary: Get transactions for a saved view
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: cursor
          in: query
          schema:
            type:
              - string
              - 'null'
        - name: filter[fromDate]
          in: query
          schema:
            type: string
            format: date
        - name: filter[toDate]
          in: query
          schema:
            type: string
            format: date
        - name: bucket
          in: query
          schema:
            type: string
            enum:
              - auto
              - day
              - week
              - month
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      transactions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Core identifiers
                            transactionId:
                              type: string
                            internalTransactionId:
                              type: string
                              description: alias of partner_transaction_id
                            physicalAccountId:
                              type: string
                            transactionAmount:
                              type: number
                              description: >-
                                Amounts / currency (both canonical names +
                                backward aliases)
                            amount:
                              type: number
                            signedAmount:
                              type: string
                              description: alias — kept for old consumers
                            currencyCode:
                              type: string
                            currency:
                              type: string
                            sourceCurrency:
                              type: string
                              description: alias — kept for old consumers
                            targetCurrency:
                              type: string
                            exchangeRate:
                              type:
                                - number
                                - 'null'
                            bookingDate:
                              type: string
                              description: Dates (Y-m-d strings — NOT ISO-8601 timestamps)
                            valueDate:
                              type: string
                            debtorIban:
                              type: string
                              description: Debtor
                            debtorBban:
                              type: string
                            debtorName:
                              type: string
                            debtorBankName:
                              type: string
                            debtorRemittanceInformation:
                              type: string
                            creditorIban:
                              type: string
                              description: Creditor
                            creditorBban:
                              type: string
                            creditorName:
                              type: string
                            creditorBankName:
                              type: string
                            creditorRemittanceInformation:
                              type: string
                            direction:
                              type: string
                              description: Processed / counterpart fields
                            counterpartAccountNumber:
                              type: string
                            counterpartName:
                              type: string
                            remittanceInformation:
                              type: string
                            description:
                              type: string
                            counterpartyBankName:
                              type: string
                              description: alias
                            countryCode:
                              type: string
                            countryCodeConfidence:
                              type:
                                - number
                                - 'null'
                            countryCodeMethod:
                              type: string
                            transactionType:
                              type: string
                              description: Transaction type (deprecated alias + canonical)
                            type:
                              type: string
                              description: alias
                            canonicalType:
                              type: string
                              description: |-
                                alias
                                Enhanced classification
                            canonicalTypeLabel:
                              type: string
                            canonicalSubtype:
                              type: string
                            canonicalChannel:
                              type: string
                            canonicalChannelLabel:
                              type: string
                            canonicalScheme:
                              type: string
                            canonicalPurpose:
                              type: string
                            classificationConfidence:
                              type:
                                - number
                                - 'null'
                            classificationMethod:
                              type: string
                            classificationCountry:
                              type: string
                            classificationProvider:
                              type: string
                            merchantCategoryCode:
                              type: string
                              description: Additional metadata
                            transactionStatus:
                              type: string
                            status:
                              type: string
                            transactionMetadata:
                              type: string
                              description: alias
                            mandateId:
                              type: string
                            referenceNumber:
                              type: string
                            isReversal:
                              type: boolean
                            counterpartType:
                              description: Counterpart classification
                              anyOf:
                                - type: string
                                - type: string
                                  enum:
                                    - other
                            counterpartTypeLabel:
                              anyOf:
                                - type: string
                                - type: string
                                  enum:
                                    - Other
                            counterpartTypeConfidence:
                              type:
                                - number
                                - 'null'
                            counterpartTypeMethod:
                              type: string
                            companyId:
                              type: string
                              description: Company binding (camelCase only — v1 contract)
                            company:
                              type:
                                - object
                                - 'null'
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                organizationNumber:
                                  type:
                                    - string
                                    - 'null'
                              required:
                                - id
                                - name
                                - organizationNumber
                            companyBindingSource:
                              type: string
                            companyBindingConfidence:
                              type:
                                - number
                                - 'null'
                            companyBoundAt:
                              type:
                                - string
                                - 'null'
                            companyBoundBy:
                              type: string
                            counterpartEntityId:
                              type: string
                              description: Counterpart entity
                            counterpart:
                              type:
                                - object
                                - 'null'
                              properties:
                                id:
                                  type: string
                                counterpartName:
                                  type: string
                                displayName:
                                  type: string
                                effectiveName:
                                  type: string
                                userAlias:
                                  type: string
                                userAliasNotes:
                                  type: string
                                hasUserAlias:
                                  type: boolean
                                type:
                                  type:
                                    - string
                                    - 'null'
                                countryCode:
                                  type: string
                                isRoot:
                                  type: string
                                directCounterpart:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    counterpartName:
                                      type: string
                                    displayName:
                                      type: string
                                  required:
                                    - id
                                    - counterpartName
                                    - displayName
                              required:
                                - id
                                - counterpartName
                                - displayName
                                - effectiveName
                                - userAlias
                                - userAliasNotes
                                - hasUserAlias
                                - type
                                - countryCode
                                - isRoot
                                - directCounterpart
                            isCardTransaction:
                              type: string
                              description: Computed classification flags
                            isInstantPayment:
                              type: string
                            isFee:
                              type: string
                            isTransfer:
                              type: string
                            hasHighConfidence:
                              type: string
                            needsReclassification:
                              type: string
                            hasCounterpartClassification:
                              type: string
                            hasHighCounterpartConfidence:
                              type: string
                            needsCounterpartClassification:
                              type: string
                            boundCompanyId:
                              type: string
                              description: >-
                                Backward-compat extras from controller
                                ->additional()
                            boundCompanyName:
                              type:
                                - string
                                - 'null'
                            raw:
                              type: string
                              description: >-
                                Raw provider data (opaque blob — verbatim, no
                                key transformation)
                            createdAt:
                              type:
                                - string
                                - 'null'
                              description: Timestamps (ISO-8601 UTC)
                            updatedAt:
                              type:
                                - string
                                - 'null'
                            trackedAccountId:
                              type: integer
                            viewId:
                              type: string
                          required:
                            - id
                            - transactionId
                            - internalTransactionId
                            - physicalAccountId
                            - transactionAmount
                            - amount
                            - signedAmount
                            - currencyCode
                            - currency
                            - sourceCurrency
                            - targetCurrency
                            - exchangeRate
                            - bookingDate
                            - valueDate
                            - debtorIban
                            - debtorBban
                            - debtorName
                            - debtorBankName
                            - debtorRemittanceInformation
                            - creditorIban
                            - creditorBban
                            - creditorName
                            - creditorBankName
                            - creditorRemittanceInformation
                            - direction
                            - counterpartAccountNumber
                            - counterpartName
                            - remittanceInformation
                            - description
                            - counterpartyBankName
                            - countryCode
                            - countryCodeConfidence
                            - countryCodeMethod
                            - transactionType
                            - type
                            - canonicalType
                            - canonicalTypeLabel
                            - canonicalSubtype
                            - canonicalChannel
                            - canonicalChannelLabel
                            - canonicalScheme
                            - canonicalPurpose
                            - classificationConfidence
                            - classificationMethod
                            - classificationCountry
                            - classificationProvider
                            - merchantCategoryCode
                            - transactionStatus
                            - status
                            - transactionMetadata
                            - mandateId
                            - referenceNumber
                            - isReversal
                            - counterpartType
                            - counterpartTypeLabel
                            - counterpartTypeConfidence
                            - counterpartTypeMethod
                            - companyId
                            - company
                            - companyBindingSource
                            - companyBindingConfidence
                            - companyBoundAt
                            - companyBoundBy
                            - counterpartEntityId
                            - counterpart
                            - isCardTransaction
                            - isInstantPayment
                            - isFee
                            - isTransfer
                            - hasHighConfidence
                            - needsReclassification
                            - hasCounterpartClassification
                            - hasHighCounterpartConfidence
                            - needsCounterpartClassification
                            - boundCompanyId
                            - boundCompanyName
                            - raw
                            - createdAt
                            - updatedAt
                            - trackedAccountId
                            - viewId
                      deniedAccountIds:
                        type: array
                        items:
                          type: string
                        minItems: 0
                        maxItems: 0
                        additionalItems: false
                    required:
                      - transactions
                      - deniedAccountIds
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          perPage:
                            type:
                              - object
                              - 'null'
                          nextCursor:
                            type: string
                          prevCursor: {}
                        required:
                          - perPage
                          - nextCursor
                          - prevCursor
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/views/{view}/aggregates:
    get:
      operationId: accounttracking.v1.views.aggregates
      description: Get aggregates for a saved view.
      summary: Get aggregates for a saved view
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  bucket:
                    type: string
                  requested_bucket:
                    type: string
                  from:
                    type: string
                  to:
                    type: string
                  accounts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        label:
                          type: string
                        currency:
                          type: string
                        color_hint:
                          type:
                            - string
                            - 'null'
                        position:
                          type: integer
                      required:
                        - id
                        - label
                        - currency
                        - color_hint
                        - position
                  currencies:
                    type: array
                    items: {}
                  denied_account_ids:
                    type: string
                  count_per_bucket:
                    type: string
                  amount_per_bucket:
                    type: string
                  running_balance:
                    type: string
                  balance_origin:
                    type: string
                required:
                  - bucket
                  - requested_bucket
                  - from
                  - to
                  - accounts
                  - currencies
                  - denied_account_ids
                  - count_per_bucket
                  - amount_per_bucket
                  - running_balance
                  - balance_origin
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/views/{view}/counterparts:
    get:
      operationId: accounttracking.v1.views.counterparts
      description: Get counterparts for a saved view.
      summary: Get counterparts for a saved view
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            ── Core identity
                            ───────────────────────────────────────────────
                        counterpartIdentifier:
                          type: string
                        name:
                          type: string
                        nameLowercase:
                          type:
                            - string
                            - 'null'
                        type:
                          type: string
                          description: >-
                            ── Type & geography
                            ────────────────────────────────────────────
                        countryCode:
                          type: string
                        visibleToEntityType:
                          type: string
                          description: >-
                            ── Access / scope
                            ──────────────────────────────────────────────
                        visibleToEntityId:
                          type: string
                        accessScope:
                          type: string
                        confidenceScore:
                          type:
                            - number
                            - 'null'
                          description: >-
                            ── Confidence & provenance
                            ──────────────────────────────────────
                        creationSource:
                          type: string
                        isActive:
                          type: boolean
                          description: >-
                            ── Status
                            ──────────────────────────────────────────────────────
                        isRoot:
                          type: boolean
                        parentId:
                          type: string
                          description: >-
                            ── Hierarchy
                            ───────────────────────────────────────────────────
                        displayName:
                          type: string
                          description: >-
                            ── Naming hierarchy
                            ────────────────────────────────────────────
                        userAlias:
                          type:
                            - string
                            - 'null'
                        userAliasNotes:
                          type:
                            - string
                            - 'null'
                        effectiveName:
                          type: string
                        hasUserAlias:
                          anyOf:
                            - type: string
                            - type: boolean
                        transactionCount:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Counts
                            ──────────────────────────────────────────────────────
                        childCount:
                          type:
                            - string
                            - 'null'
                        transactionVolumes:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Service-computed nested objects
                            ─────────────────────────────
                        ownership:
                          type:
                            - string
                            - 'null'
                        relationshipSummary:
                          type:
                            - string
                            - 'null'
                        boundEntities:
                          type:
                            - string
                            - 'null'
                        entityMappings:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Deprecated compatibility fields
                            ───────────────────
                        parent:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Parent (optional, included when
                            include_parent=true) ─────────
                        metadata:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Metadata (opaque)
                            ────────────────────────────────────────────
                        establishedAt:
                          type:
                            - string
                            - 'null'
                          description: >-
                            ── Timestamps
                            ──────────────────────────────────────────────────
                        createdAt:
                          type:
                            - string
                            - 'null'
                        updatedAt:
                          type:
                            - string
                            - 'null'
                        trackedAccountIds:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - counterpartIdentifier
                        - name
                        - nameLowercase
                        - type
                        - countryCode
                        - visibleToEntityType
                        - visibleToEntityId
                        - accessScope
                        - confidenceScore
                        - creationSource
                        - isActive
                        - isRoot
                        - parentId
                        - displayName
                        - userAlias
                        - userAliasNotes
                        - effectiveName
                        - hasUserAlias
                        - transactionCount
                        - childCount
                        - transactionVolumes
                        - ownership
                        - relationshipSummary
                        - boundEntities
                        - entityMappings
                        - parent
                        - metadata
                        - establishedAt
                        - createdAt
                        - updatedAt
                        - trackedAccountIds
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          perPage:
                            type:
                              - object
                              - 'null'
                          currentPage:
                            type:
                              - object
                              - 'null'
                          lastPage:
                            type: integer
                        required:
                          - total
                          - perPage
                          - currentPage
                          - lastPage
                      deniedAccountIds:
                        type: array
                        items:
                          type: string
                        minItems: 0
                        maxItems: 0
                        additionalItems: false
                      timeframe:
                        type: object
                        properties:
                          startDate:
                            type: string
                          endDate:
                            type: string
                        required:
                          - startDate
                          - endDate
                    required:
                      - requestId
                      - pagination
                      - deniedAccountIds
                      - timeframe
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/views/{view}/report:
    post:
      operationId: accounttracking.v1.views.report
      description: >-
        Generate a PDF report for a merged account view.


        Returns binary application/pdf — not wrapped in the {data,meta}
        envelope.

        This endpoint does not support the Idempotency-Key header.
      summary: Generate a PDF report for a view
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filename:
                  type:
                    - string
                    - 'null'
                  maxLength: 255
                filters:
                  type: object
                  properties:
                    fromDate:
                      type:
                        - string
                        - 'null'
                      format: date
                    toDate:
                      type:
                        - string
                        - 'null'
                      format: date
                    direction:
                      type:
                        - string
                        - 'null'
                      enum:
                        - Incoming
                        - Outgoing
                charts:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        maxLength: 60
                      image_base64:
                        type: string
                      width:
                        type:
                          - integer
                          - 'null'
                        minimum: 1
                        maximum: 4000
                      height:
                        type:
                          - integer
                          - 'null'
                        minimum: 1
                        maximum: 4000
                    required:
                      - id
                      - image_base64
                  minItems: 1
                  maxItems: 6
              required:
                - charts
      responses:
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/views/{view}/favorite:
    post:
      operationId: accounttracking.v1.views.favorite
      description: Pin a view as a favorite for the current user.
      summary: Pin a view as a favorite
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      viewId:
                        type: string
                      isFavorite:
                        type: boolean
                    required:
                      - viewId
                      - isFavorite
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    delete:
      operationId: accounttracking.v1.views.unfavorite
      description: Unpin a view from favorites.
      summary: Unpin a view from favorites
      tags:
        - MergedViewV1
      parameters:
        - name: view
          in: path
          required: true
          description: The view ID
          schema:
            type: string
            format: uuid
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      viewId:
                        type: string
                      isFavorite:
                        type: boolean
                    required:
                      - viewId
                      - isFavorite
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /oauth/v1/authorize:
    get:
      operationId: oauth.v1.authorize
      tags:
        - OAuthAuthorize
      parameters:
        - name: client_id
          in: query
          schema:
            type: string
        - name: redirect_uri
          in: query
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
        - name: response_type
          in: query
          schema:
            type: string
        - name: scope
          in: query
          schema:
            type: string
        - name: code_challenge
          in: query
          schema:
            type: string
        - name: code_challenge_method
          in: query
          schema:
            type: string
        - name: entity_type
          in: query
          description: |-
            The target entity may not be known yet at authorize time (e.g.
            an MCP client that lets the user pick it on the consent
            screen) — passed through opaquely, unvalidated, if present.
          schema:
            type: string
        - name: entity_id
          in: query
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      security: []
      summary: Authorize
  /oauth/v1/consent/{authorizationId}:
    get:
      operationId: oauth.v1.consent.show
      summary: Render everything the consent
      tags:
        - OAuthConsent
      parameters:
        - name: authorizationId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      clientName:
                        type: string
                      clientLogoUrl:
                        type: string
                        description: The connector's branding, shown on the consent screen.
                      homepageUrl:
                        type: string
                      redirectUri:
                        type: string
                      requestedRoles:
                        type: array
                        description: >-
                          Each requested role also carries includedCapabilities
                          (LEX-124):

                          its FULL contents (area -> named permissions), never
                          filtered

                          through the consentable-capabilities whitelist — a
                          role grant

                          is wholesale (AppService::create() -> assignRoleTo()),
                          so the

                          whitelist only gates the separate
                          requestedCapabilities path

                          below. Global roles only. Read together with each
                          entry in

                          availableScopes[].roleGrantability for the SAME role
                          (missing/

                          dormant), the frontend derives, per selected scope,
                          which of

                          these included capabilities are active vs. dormant vs.
                          blocked

                          — see availableScopes' doc comment below for that
                          pairing.
                        items: {}
                      requestedCapabilities:
                        type: array
                        description: >-
                          Capability consent Phase 1: grouped by area, from EP
                          definitions

                          ∩ the consentable whitelist — same source as the role
                          presets'

                          capability groups, filtered down to what THIS request
                          (or, on

                          an empty request, the connector's preset — already
                          resolved

                          into the state's capability_keys at authorize time)
                          asked for.
                        items:
                          type: object
                          properties:
                            area:
                              type: string
                            areaName:
                              type: string
                            capabilities:
                              type: array
                              items: {}
                          required:
                            - area
                            - areaName
                            - capabilities
                      delegationRequested:
                        type: boolean
                        description: >-
                          Whether the authorization request asked for delegated
                          access

                          ("act on your behalf"). Only ever true when the
                          connector

                          supports delegate mode. The user's actual choice is
                          returned

                          via the `delegate` field of the approve request.
                      scopeEntity:
                        description: >-
                          The scope resolved from the request (X-Scope header or
                          the user's

                          own personal scope) — the picker's DEFAULT selection.
                        anyOf:
                          - type: object
                            properties:
                              type:
                                type: string
                              id:
                                type: string
                              name:
                                type:
                                  - string
                                  - 'null'
                            required:
                              - type
                              - id
                              - name
                          - type: 'null'
                          - type: object
                            properties:
                              type:
                                type: string
                                const: user
                              id:
                                type: string
                              name:
                                type: string
                            required:
                              - type
                              - id
                              - name
                      availableScopes:
                        type: array
                        description: >-
                          Every scope the user has standing on — the picker's
                          OPTIONS,

                          each carrying its own roleGrantability: for every
                          requested

                          role, whether picking THIS scope would let the grant
                          succeed

                          (a real block, e.g. escalation beyond the user's own
                          role),

                          plus which of the role's included capabilities are
                          dormant on

                          this scope (informational only — "included in this
                          role, not
                           active until <product> is activated"; never a reason the role
                          is unavailable). Lets the screen warn BEFORE Allow
                          instead of

                          only after. The user's choice is sent back as the
                          X-Scope

                          header on approve, where resolveScopeEntity
                          re-validates it

                          (actorCanAccessScope) and grantConsent re-checks the
                          real

                          ceiling — this payload is guidance, not the
                          enforcement point.

                          Each scope also carries installEligible: whether
                          picking it

                          would let the org-owned consent branch through (the

                          apps.install capability); false means that option
                          renders

                          disabled for the scope, and approve would return 403

                          apps_install_required regardless.
                        items: {}
                    required:
                      - clientName
                      - clientLogoUrl
                      - homepageUrl
                      - redirectUri
                      - requestedRoles
                      - requestedCapabilities
                      - delegationRequested
                      - scopeEntity
                      - availableScopes
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: consent_expired
                      message:
                        type: string
                        const: >-
                          This authorization request has expired, was already
                          decided, or does not exist.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    post:
      operationId: oauth.v1.consent.store
      summary: The user's decision.
      tags:
        - OAuthConsent
      parameters:
        - name: authorizationId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentDecisionRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      redirectUri:
                        type: string
                    required:
                      - redirectUri
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: invalid_scope
                          message:
                            type: string
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: invalid_scope
                          message:
                            type: string
                            const: Delegation was not requested at authorize time.
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: invalid_scope
                          message:
                            type: string
                            const: >-
                              The granted roles/capabilities must be a subset of
                              what was requested at authorize time.
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: invalid_scope
                          message:
                            type: string
                            const: At least one role or capability must be granted.
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: consent_expired
                      message:
                        type: string
                        const: >-
                          This authorization request has expired, was already
                          decided, or does not exist.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /oauth/v1/consents:
    get:
      operationId: oauth.v1.consents.index
      summary: The authorizations the current user has
      tags:
        - OAuthConsentManagement
      parameters:
        - name: filter[status]
          in: query
          schema:
            type: string
            default: active
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthConsentResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /oauth/v1/consents/{consent}:
    delete:
      operationId: oauth.v1.consents.destroy
      summary: Revoke one of your connections.
      tags:
        - OAuthConsentManagement
      parameters:
        - name: consent
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /oauth/v1/consents/{consent}/delegation:
    delete:
      operationId: oauth.v1.consents.delegation.destroy
      summary: Withdraw the app's
      tags:
        - OAuthConsentManagement
      parameters:
        - name: consent
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /oauth/v1/revoke:
    post:
      operationId: oauth.v1.revoke
      description: |-
        RFC 7009 revocation endpoint. Pass the token to revoke (a refresh token
        or an access token) with the same client authentication you use at the
        token endpoint. Revoking a refresh token disconnects the connection it
        belongs to entirely; revoking an access token invalidates only that
        bearer. Always returns `200` for an authenticated client, whether or not
        the token was known.
      summary: Revoke a token
      tags:
        - OAuthRevocation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The refresh token or access token to revoke.
                token_type_hint:
                  type: string
                  description: >-
                    Optional: `refresh_token` or `access_token`. A wrong hint is
                    tolerated — both types are searched.
                client_id:
                  type: string
                  description: >-
                    Your Connector client id. Required here unless sent via HTTP
                    Basic auth.
                client_secret:
                  type: string
                  description: >-
                    Your Connector client secret (confidential clients only)
                    unless sent via HTTP Basic auth.
              required:
                - token
      responses:
        '200':
          description: >-
            Processed. The body is an empty JSON object `{}`. Returned whether
            or not the token existed (RFC 7009 §2.2).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
        '400':
          description: >-
            RFC 6749 §5.2 flat error — `invalid_request` when `token` is missing
            or credentials were sent in both header and body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
                required:
                  - error
                  - error_description
        '401':
          description: Client authentication failed (`invalid_client`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
                required:
                  - error
                  - error_description
      security: []
  /oauth/v1/token:
    post:
      operationId: oauth.v1.token
      description: |-
        OAuth 2.0 token endpoint (RFC 6749). Dispatches on `grant_type`:
        `client_credentials` (a first-party App authenticating with its own
        client-credential set), `authorization_code` (a Connector redeeming a
        consent-minted one-time code — with PKCE `S256` when the authorize
        request carried a `code_challenge`, which is mandatory for public
        clients) or `refresh_token` (a Connector rotating a refresh token from
        an earlier redemption for a fresh access token). Client credentials may
        be sent either as an HTTP Basic `Authorization` header or as
        `client_id`/`client_secret` body fields — never both, and never in the
        query string.

        Request and response are RFC-flat (`application/x-www-form-urlencoded`
        or JSON in, plain JSON out) — NOT the platform `{data,meta}` envelope —
        so standard OAuth client libraries work unmodified. The issued bearer
        token expires after `expires_in` seconds. The `authorization_code` and
        `refresh_token` grants also return a rotating `refresh_token` (LEX-130);
        `client_credentials` does not.
      summary: Issue an access token
      tags:
        - OAuthToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: >-
                    One of `client_credentials`, `authorization_code` or
                    `refresh_token`.
                  example: authorization_code
                client_id:
                  type: string
                  description: >-
                    The client id (App client credential, or Connector client
                    id). Required here unless sent via HTTP Basic auth.
                client_secret:
                  type: string
                  description: >-
                    The client secret. Required for confidential clients unless
                    sent via HTTP Basic auth; public (PKCE-only) clients have
                    none.
                code:
                  type: string
                  description: >-
                    `authorization_code` grant only: the one-time authorization
                    code returned to your redirect URI.
                redirect_uri:
                  type: string
                  description: >-
                    `authorization_code` grant only: must exactly match the
                    redirect_uri used in the authorize request.
                code_verifier:
                  type: string
                  description: >-
                    `authorization_code` grant only: the PKCE verifier matching
                    the `code_challenge` sent at authorize time. Required
                    whenever the code was issued with PKCE (always, for public
                    clients).
                refresh_token:
                  type: string
                  description: >-
                    `refresh_token` grant only: the refresh token returned by a
                    previous authorization_code redemption or refresh. One-use —
                    each refresh returns a new one.
                scope:
                  type: string
                  description: >-
                    `client_credentials` grant only: accepted but currently
                    ignored (reserved).
              required:
                - grant_type
      responses:
        '200':
          description: >-
            Token issued. `access_token` authenticates as the App; send it as
            `Authorization: Bearer <access_token>`. The token expires after
            `expires_in` seconds. The `authorization_code` and `refresh_token`
            grants also return a rotating `refresh_token` (valid until the
            connection is revoked or 90 days unused); `client_credentials` does
            not.
          content:
            application/json:
              schema:
                type: object
                examples:
                  - access_token: 1|9x7K2mQpR4vL8nW3zC6hT1sD5fG0aJ2bE9cY4uI7oP
                    token_type: Bearer
                    expires_in: 3600
                    refresh_token: rt_4Kf…
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                  expires_in:
                    type: integer
                  refresh_token:
                    type: string
                required:
                  - access_token
                  - token_type
                  - expires_in
        '400':
          description: >-
            RFC 6749 §5.2 flat error. `error` is one of `invalid_request`
            (missing/malformed parameter, or credentials in both header and
            body), `unsupported_grant_type`, or `invalid_grant`. `invalid_grant`
            covers an authorization code that is invalid, expired, already used,
            bound to a different client/redirect_uri, or that failed PKCE
            verification — and, on the `refresh_token` grant, a refresh token
            that is unknown, already used (each refresh rotates it), expired
            after its idle window, presented by a different client, or whose
            connection, app or connector is no longer valid.
          content:
            application/json:
              schema:
                type: object
                examples:
                  - error: invalid_grant
                    error_description: The authorization code is invalid.
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
                required:
                  - error
                  - error_description
        '401':
          description: >-
            Client authentication failed (`error` = `invalid_client`) — unknown
            client, bad secret, expired credential, or temporary lockout after
            repeated failures.
          content:
            application/json:
              schema:
                type: object
                examples:
                  - error: invalid_client
                    error_description: Client authentication failed.
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
                required:
                  - error
                  - error_description
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    const: server_error
                  error_description:
                    type: string
                    const: An unexpected error occurred while processing the request.
                required:
                  - error
                  - error_description
      security: []
  /productmanagement/v1/packages:
    get:
      operationId: productmanagement.v1.packages.index
      description: GET productmanagement/v1/packages
      summary: List public active packages for the entity scope.
      tags:
        - PackageCatalogV1
      parameters:
        - name: type
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PackageV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /productmanagement/v1/packages/{slug}:
    get:
      operationId: productmanagement.v1.packages.show
      description: GET productmanagement/v1/packages/{slug}
      summary: Get package details by slug
      tags:
        - PackageCatalogV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PackageV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /auth/v1/forgot-password:
    post:
      operationId: auth.v1.forgot-password
      description: >-
        Rate-limited by IP. May require a reCAPTCHA token. Always returns
        success

        to prevent email enumeration.
      summary: Request a password reset email
      tags:
        - PasswordResetV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordV1Request'
      responses:
        '200':
          description: Always return success to prevent email enumeration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sent:
                        type: boolean
                    required:
                      - sent
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '429':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: too_many_attempts
                      message:
                        type: string
                        const: >-
                          Too many password reset attempts. Please try again
                          later.
                      details:
                        type: object
                        properties:
                          retry_after:
                            type: integer
                        required:
                          - retry_after
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Password reset request failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /auth/v1/reset-password/{uuid}:
    get:
      operationId: auth.v1.reset-password.validate
      description: >-
        Returns the email associated with the token so the reset form can
        pre-fill it.
      summary: Validate a password reset token
      tags:
        - PasswordResetV1
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      valid:
                        type: boolean
                      email:
                        type: string
                    required:
                      - valid
                      - email
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                        enum:
                          - This password reset link is invalid or has expired.
                          - Invalid reset token.
                          - Account not found.
                          - Password reset failed. Please try again.
                          - An error occurred. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Token validation failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /auth/v1/reset-password:
    post:
      operationId: auth.v1.reset-password
      description: Rate-limited by token.
      summary: Reset the password using a valid token
      tags:
        - PasswordResetV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      reset:
                        type: boolean
                    required:
                      - reset
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '429':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: too_many_attempts
                      message:
                        type: string
                        const: >-
                          Too many password reset attempts. Please request a new
                          reset link.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Password reset failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /auth/v1/password:
    post:
      operationId: auth.v1.password.set
      description: |-
        Two paths:
          1. User has active local credential: verify current_password then update.
          2. User has no local credential (OAuth-only / invited): bootstrap if
             allow_bootstrap is enabled and session has a recent-auth marker.
      summary: Set or bootstrap the local password
      tags:
        - PasswordV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPasswordV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          bootstrapped:
                            type: boolean
                        required:
                          - bootstrapped
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          updated:
                            type: boolean
                        required:
                          - updated
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: server_error
                          message:
                            type: string
                            const: Could not set password. Please try again.
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: set_failed
                          message:
                            type: string
                            const: Could not set password. Please try again.
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /entitypermissions/v1/permissions/check:
    post:
      operationId: entitypermissions.v1.permissions.check
      summary: Check whether a user has a permission
      tags:
        - PermissionCheckV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckPermissionV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PermissionCheckV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitypermissions/v1/permissions/check-batch:
    post:
      operationId: entitypermissions.v1.permissions.check-batch
      summary: Check multiple permissions for a user
      tags:
        - PermissionCheckV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckPermissionBatchV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PermissionCheckBatchV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitypermissions/v1/permissions/roles/check:
    post:
      operationId: entitypermissions.v1.permissions.roles.check
      summary: Check whether a user has a role
      tags:
        - PermissionCheckV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HasRoleV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/HasRoleV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitypermissions/v1/definitions:
    get:
      operationId: entitypermissions.v1.definitions
      tags:
        - PermissionDefinitionsV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PermissionDefinitionsV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      summary: Definitions
  /users/v1/me/tokens:
    get:
      operationId: users.v1.me.tokens.index
      summary: List the caller's own PATs. Never includes
      tags:
        - PersonalAccessTokenV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        createdAt:
                          type:
                            - string
                            - 'null'
                        lastUsedAt:
                          type:
                            - string
                            - 'null'
                        expiresAt:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - name
                        - createdAt
                        - lastUsedAt
                        - expiresAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: users.v1.me.tokens.store
      summary: Issue a new PAT. expiresAt defaults to
      tags:
        - PersonalAccessTokenV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePersonalAccessTokenV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/NewAccessToken'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /users/v1/me/tokens/{tokenId}/rotate:
    post:
      operationId: users.v1.me.tokens.rotate
      summary: Mint a new PAT with the
      tags:
        - PersonalAccessTokenV1
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/NewAccessToken'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Token not found.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /users/v1/me/tokens/{tokenId}:
    patch:
      operationId: users.v1.me.tokens.update
      summary: Rename and/or re-extend a PAT.
      tags:
        - PersonalAccessTokenV1
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePersonalAccessTokenV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      lastUsedAt:
                        type:
                          - string
                          - 'null'
                      expiresAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - createdAt
                      - lastUsedAt
                      - expiresAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Token not found.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: users.v1.me.tokens.destroy
      summary: Revoke a PAT. 204 on success.
      tags:
        - PersonalAccessTokenV1
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Token not found.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /productmanagement/v1/products/{slug}/status:
    get:
      operationId: productmanagement.v1.products.status
      description: GET productmanagement/v1/products/{slug}/status
      summary: Get activation status for a product
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ProductActivationV1Resource'
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          productSlug:
                            type: string
                          status:
                            type: string
                            const: not_activated
                        required:
                          - productSlug
                          - status
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /productmanagement/v1/products/{slug}/activate/credentials:
    get:
      operationId: productmanagement.v1.products.activate.credentials.check
      description: GET productmanagement/v1/products/{slug}/activate/credentials
      summary: Check credential availability for activation
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: integrationId
          in: query
          schema:
            type: string
        - name: integration_id
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          integrationId:
                            type:
                              - string
                              - 'null'
                          hasCredentials:
                            anyOf:
                              - type: string
                              - type: boolean
                          credentialLevel:
                            type:
                              - string
                              - 'null'
                          canOverride:
                            anyOf:
                              - type: string
                              - type: boolean
                          hasEntityCredentials:
                            anyOf:
                              - type: string
                              - type: boolean
                          authenticationMethod:
                            type:
                              - string
                              - 'null'
                          credentialSchema:
                            anyOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                                minItems: 0
                                maxItems: 0
                                additionalItems: false
                          existingCredentials:
                            anyOf:
                              - type: string
                              - type: object
                                properties:
                                  global:
                                    type: 'null'
                                  entity:
                                    type: 'null'
                                required:
                                  - global
                                  - entity
                          credentialMode:
                            anyOf:
                              - type: string
                              - type: string
                                enum:
                                  - system_default
                        required:
                          - integrationId
                          - hasCredentials
                          - credentialLevel
                          - canOverride
                          - hasEntityCredentials
                          - authenticationMethod
                          - credentialSchema
                          - existingCredentials
                          - credentialMode
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: object
                    properties:
                      data:
                        type: array
                        items: {}
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: productmanagement.v1.products.activate.credentials.configure
      description: PUT productmanagement/v1/products/{slug}/activate/credentials
      summary: Configure entity-specific credentials for activation
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigureCredentialsV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ProductActivationV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /productmanagement/v1/products/{slug}/activate/complete:
    post:
      operationId: productmanagement.v1.products.activate.complete
      description: POST productmanagement/v1/products/{slug}/activate/complete
      summary: Complete product activation
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ProductActivationV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: activation_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /productmanagement/v1/products/{slug}/activate/cancel:
    delete:
      operationId: productmanagement.v1.products.activate.cancel
      description: DELETE productmanagement/v1/products/{slug}/activate/cancel
      summary: Cancel a pending/configuring activation
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: activation_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /productmanagement/v1/products/{slug}/activate:
    delete:
      operationId: productmanagement.v1.products.deactivate
      description: DELETE productmanagement/v1/products/{slug}/activate
      summary: Deactivate a product
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: deactivation_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
    post:
      operationId: productmanagement.v1.products.activate
      description: POST productmanagement/v1/products/{slug}/activate
      summary: Begin product activation (creates pending activation).
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ProductActivationV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: activation_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /productmanagement/v1/products/{slug}/activate/integrations:
    put:
      operationId: productmanagement.v1.products.activate.integrations
      description: PUT productmanagement/v1/products/{slug}/activate/integrations
      summary: Select integration providers for activation (multi-select)
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectIntegrationsV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ProductActivationV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /productmanagement/v1/products/{slug}/integrations:
    get:
      operationId: productmanagement.v1.products.integrations.list
      description: GET productmanagement/v1/products/{slug}/integrations
      summary: List the integrations attached to a specific activation
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        integrationId:
                          type: string
                        integration:
                          type:
                            - object
                            - 'null'
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            slug:
                              type: string
                            health:
                              type: string
                            status:
                              type:
                                - string
                                - 'null'
                            supportedCountries:
                              type:
                                - array
                                - 'null'
                              items: {}
                          required:
                            - id
                            - name
                            - slug
                            - health
                            - status
                            - supportedCountries
                        status:
                          type: string
                        attachedAt:
                          type: string
                        pausedAt:
                          type: string
                      required:
                        - id
                        - integrationId
                        - integration
                        - status
                        - attachedAt
                        - pausedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: productmanagement.v1.products.integrations.attach
      description: POST productmanagement/v1/products/{slug}/integrations
      summary: Attach an additional integration to an existing activation
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachIntegrationV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      integrationId:
                        type: string
                      status:
                        type: string
                      attachedAt:
                        type: string
                    required:
                      - id
                      - integrationId
                      - status
                      - attachedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /productmanagement/v1/products/{slug}/integrations/{integrationId}:
    delete:
      operationId: productmanagement.v1.products.integrations.detach
      description: DELETE productmanagement/v1/products/{slug}/integrations/{integrationId}
      summary: Detach an integration from an existing activation
      tags:
        - ProductActivationV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: integrationId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: activation_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /productmanagement/v1/activations:
    get:
      operationId: productmanagement.v1.activations.index
      description: GET productmanagement/v1/activations
      summary: List entity's activated products
      tags:
        - ProductActivationV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductActivationV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /productmanagement/v1/products:
    get:
      operationId: productmanagement.v1.products.index
      description: GET productmanagement/v1/products
      summary: List available products for the current entity scope
      tags:
        - ProductCatalogV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /productmanagement/v1/products/{slug}/integrations/eligible:
    get:
      operationId: productmanagement.v1.products.integrations.eligible
      description: >-
        GET
        productmanagement/v1/products/{slug}/integrations/eligible?regions[]=NO&regions[]=DK
      summary: >-
        List eligible integrations for a product, annotated with the entity's
        configuration state.
      tags:
        - ProductCatalogV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        slug:
                          type: string
                        description:
                          type:
                            - string
                            - 'null'
                        health:
                          type: string
                        status:
                          type:
                            - string
                            - 'null'
                        supportedCountries:
                          anyOf:
                            - type: array
                              items: {}
                            - type: array
                              items:
                                type: string
                        coveredRegions:
                          type: string
                        missingRegions:
                          type: string
                        isConfigured:
                          type: boolean
                        isAttached:
                          type: boolean
                        isDefault:
                          type: boolean
                      required:
                        - id
                        - name
                        - slug
                        - description
                        - health
                        - status
                        - supportedCountries
                        - coveredRegions
                        - missingRegions
                        - isConfigured
                        - isAttached
                        - isDefault
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      requestedRegions:
                        type:
                          - array
                          - 'null'
                        items: {}
                      productSlug:
                        type: string
                      productType:
                        type: string
                    required:
                      - requestId
                      - requestedRegions
                      - productSlug
                      - productType
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /productmanagement/v1/products/{slug}/eligibility:
    get:
      operationId: productmanagement.v1.products.eligibility
      description: GET productmanagement/v1/products/{slug}/eligibility
      summary: Check entity eligibility for a specific product
      tags:
        - ProductCatalogV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ProductEligibilityV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /productmanagement/v1/products/{slug}:
    get:
      operationId: productmanagement.v1.products.show
      description: GET productmanagement/v1/products/{slug}
      summary: Show product details with features
      tags:
        - ProductCatalogV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ProductV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /productmanagement/v1/products/{slug}/credentials:
    get:
      operationId: productmanagement.v1.products.credentials.show
      description: GET productmanagement/v1/products/{slug}/credentials
      summary: Get credential status for an active product
      tags:
        - ProductCredentialV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          integrationId:
                            type:
                              - string
                              - 'null'
                          hasCredentials:
                            type: string
                          credentialLevel:
                            type:
                              - string
                              - 'null'
                            enum:
                              - entity
                              - global
                              - null
                          hasEntityCredentials:
                            type: boolean
                          authenticationMethod:
                            type: string
                          credentialSchema:
                            type: array
                            items: {}
                          existingCredentials:
                            type: object
                            properties:
                              global:
                                type: object
                                additionalProperties:
                                  type:
                                    - string
                                    - 'null'
                              entity:
                                type: object
                                additionalProperties:
                                  type:
                                    - string
                                    - 'null'
                            required:
                              - global
                              - entity
                          credentialMetadata:
                            type: object
                            properties:
                              global:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  name:
                                    type: string
                                  slug:
                                    type: string
                                  schema_type:
                                    type:
                                      - string
                                      - 'null'
                                  status:
                                    type: string
                                  tier:
                                    type: string
                                  field_count:
                                    type: integer
                                  configured:
                                    type: boolean
                                  age_days:
                                    type: string
                                  last_rotated_at:
                                    type: string
                                  expires_at:
                                    type: string
                                  created_at:
                                    type: string
                                required:
                                  - id
                                  - name
                                  - slug
                                  - schema_type
                                  - status
                                  - tier
                                  - field_count
                                  - configured
                                  - age_days
                                  - last_rotated_at
                                  - expires_at
                                  - created_at
                              entity:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  name:
                                    type: string
                                  slug:
                                    type: string
                                  schema_type:
                                    type:
                                      - string
                                      - 'null'
                                  status:
                                    type: string
                                  tier:
                                    type: string
                                  field_count:
                                    type: integer
                                  configured:
                                    type: boolean
                                  age_days:
                                    type: string
                                  last_rotated_at:
                                    type: string
                                  expires_at:
                                    type: string
                                  created_at:
                                    type: string
                                required:
                                  - id
                                  - name
                                  - slug
                                  - schema_type
                                  - status
                                  - tier
                                  - field_count
                                  - configured
                                  - age_days
                                  - last_rotated_at
                                  - expires_at
                                  - created_at
                            required:
                              - global
                              - entity
                          credentialMode:
                            type: string
                          lastRotatedAt:
                            type:
                              - string
                              - 'null'
                        required:
                          - integrationId
                          - hasCredentials
                          - credentialLevel
                          - hasEntityCredentials
                          - authenticationMethod
                          - credentialSchema
                          - existingCredentials
                          - credentialMetadata
                          - credentialMode
                          - lastRotatedAt
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          hasCredentials:
                            type: boolean
                          credentialLevel:
                            type: 'null'
                          authenticationMethod:
                            type: 'null'
                          credentialSchema:
                            type: array
                            items:
                              type: string
                            minItems: 0
                            maxItems: 0
                            additionalItems: false
                          existingCredentials:
                            type: object
                            properties:
                              global:
                                type: 'null'
                              entity:
                                type: 'null'
                            required:
                              - global
                              - entity
                          credentialMode:
                            type: string
                            const: system_default
                        required:
                          - hasCredentials
                          - credentialLevel
                          - authenticationMethod
                          - credentialSchema
                          - existingCredentials
                          - credentialMode
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: productmanagement.v1.products.credentials.update
      description: PUT productmanagement/v1/products/{slug}/credentials
      summary: >-
        Update credentials for an active product (rotation / new entity-level
        set)
      tags:
        - ProductCredentialV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCredentialsV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        const: ok
                      message:
                        type: string
                        const: Credentials updated successfully.
                    required:
                      - status
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: productmanagement.v1.products.credentials.reset
      description: DELETE productmanagement/v1/products/{slug}/credentials
      summary: Reset to global credentials by deactivating entity-level credentials.
      tags:
        - ProductCredentialV1
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: no_entity_credentials
                          message:
                            type: string
                            const: No entity credentials to reset.
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: no_integration
                          message:
                            type: string
                            const: >-
                              No integration configured. Specify integrationId
                              when this product has multiple attached
                              integrations.
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /entitymanagement/v1/projects:
    get:
      operationId: entitymanagement.v1.projects.index
      description: |-
        User-scoping: only returns active projects where the user has an active
        assigned, owner, or collaborator relationship.
      summary: List projects accessible by the authenticated user.
      tags:
        - Project
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: entitymanagement.v1.projects.store
      summary: Create a new project.
      tags:
        - Project
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreProjectRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      projectCode:
                        type:
                          - string
                          - 'null'
                      projectType:
                        type: string
                      status:
                        type: string
                      priority:
                        type: string
                      startDate:
                        type: string
                      endDate:
                        type: string
                      deadlineDate:
                        type: string
                      budget:
                        type:
                          - string
                          - 'null'
                      currencyCode:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      isActive:
                        type: boolean
                      archivedAt:
                        type:
                          - string
                          - 'null'
                      createdBy:
                        type: integer
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - projectCode
                      - projectType
                      - status
                      - priority
                      - startDate
                      - endDate
                      - deadlineDate
                      - budget
                      - currencyCode
                      - metadata
                      - isActive
                      - archivedAt
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/projects/overdue:
    get:
      operationId: entitymanagement.v1.projects.overdue
      summary: Get overdue projects assigned to the authenticated user.
      tags:
        - Project
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /entitymanagement/v1/projects/upcoming-deadlines:
    get:
      operationId: entitymanagement.v1.projects.upcoming-deadlines
      description: Same whereExists pattern — avoids broken whereUserIsAssigned scope.
      summary: Get projects with upcoming deadlines for the authenticated user.
      tags:
        - Project
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /entitymanagement/v1/projects/{project}:
    get:
      operationId: entitymanagement.v1.projects.show
      summary: Show a single project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      projectCode:
                        type:
                          - string
                          - 'null'
                      projectType:
                        type: string
                      status:
                        type: string
                      priority:
                        type: string
                      startDate:
                        type: string
                      endDate:
                        type: string
                      deadlineDate:
                        type: string
                      budget:
                        type:
                          - string
                          - 'null'
                      currencyCode:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      isActive:
                        type: boolean
                      archivedAt:
                        type:
                          - string
                          - 'null'
                      createdBy:
                        type: integer
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      assignedUserCount:
                        type: integer
                      assignedGroupCount:
                        type: integer
                      isOverdue:
                        type: boolean
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - projectCode
                      - projectType
                      - status
                      - priority
                      - startDate
                      - endDate
                      - deadlineDate
                      - budget
                      - currencyCode
                      - metadata
                      - isActive
                      - archivedAt
                      - createdBy
                      - createdAt
                      - updatedAt
                      - assignedUserCount
                      - assignedGroupCount
                      - isOverdue
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: entitymanagement.v1.projects.update
      summary: Update a project (PUT = full replace, PATCH = partial).
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      projectCode:
                        type:
                          - string
                          - 'null'
                      projectType:
                        type: string
                      status:
                        type: string
                      priority:
                        type: string
                      startDate:
                        type: string
                      endDate:
                        type: string
                      deadlineDate:
                        type: string
                      budget:
                        type:
                          - string
                          - 'null'
                      currencyCode:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      isActive:
                        type: boolean
                      archivedAt:
                        type:
                          - string
                          - 'null'
                      createdBy:
                        type: integer
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - projectCode
                      - projectType
                      - status
                      - priority
                      - startDate
                      - endDate
                      - deadlineDate
                      - budget
                      - currencyCode
                      - metadata
                      - isActive
                      - archivedAt
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: entitymanagement.v1.projects.patch
      summary: Update a project (PUT = full replace, PATCH = partial).
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type:
                          - string
                          - 'null'
                      projectCode:
                        type:
                          - string
                          - 'null'
                      projectType:
                        type: string
                      status:
                        type: string
                      priority:
                        type: string
                      startDate:
                        type: string
                      endDate:
                        type: string
                      deadlineDate:
                        type: string
                      budget:
                        type:
                          - string
                          - 'null'
                      currencyCode:
                        type: string
                      metadata:
                        type:
                          - array
                          - 'null'
                        items: {}
                      isActive:
                        type: boolean
                      archivedAt:
                        type:
                          - string
                          - 'null'
                      createdBy:
                        type: integer
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - projectCode
                      - projectType
                      - status
                      - priority
                      - startDate
                      - endDate
                      - deadlineDate
                      - budget
                      - currencyCode
                      - metadata
                      - isActive
                      - archivedAt
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/projects/{project}/archive:
    post:
      operationId: entitymanagement.v1.projects.archive
      summary: Archive a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Project archived successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /entitymanagement/v1/projects/{project}/unarchive:
    post:
      operationId: entitymanagement.v1.projects.unarchive
      summary: Unarchive a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Project unarchived successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /entitymanagement/v1/projects/{project}/assignments:
    get:
      operationId: entitymanagement.v1.projects.assignments.index
      summary: List all assignments (users + groups) for a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/EntityRelationship'
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/EntityRelationship'
                    required:
                      - users
                      - groups
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    delete:
      operationId: entitymanagement.v1.projects.assignments.destroy
      summary: Remove an assignment from a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: entityType
          in: query
          required: true
          schema:
            type: string
            enum:
              - user
              - group
        - name: entityId
          in: query
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/projects/{project}/assign-user:
    post:
      operationId: entitymanagement.v1.projects.assignments.assign-user
      summary: Assign a user to a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignProjectUserRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: User assigned to project successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/projects/{project}/assign-group:
    post:
      operationId: entitymanagement.v1.projects.assignments.assign-group
      summary: Assign a group to a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignProjectGroupRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Group assigned to project successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/projects/{project}/users/{userId}:
    put:
      operationId: entitymanagement.v1.projects.users.update-role
      summary: Update a user's role on a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectUserRoleRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: User role updated successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/projects/{project}/users/{userId}/permissions:
    get:
      operationId: entitymanagement.v1.projects.users.permissions.index
      summary: Get a user's permissions on a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      userId:
                        type: integer
                      projectId:
                        type: string
                      roles:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                            type:
                              type: string
                            assignedAt:
                              type: string
                          required:
                            - key
                            - type
                            - assignedAt
                      permissions:
                        type: array
                        items:
                          type: string
                      permissionCount:
                        type: integer
                    required:
                      - userId
                      - projectId
                      - roles
                      - permissions
                      - permissionCount
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: entitymanagement.v1.projects.users.permissions.store
      summary: Grant a specific permission to a user on a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantProjectPermissionRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Permission granted successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/projects/{project}/users/{userId}/permissions/{permission}:
    delete:
      operationId: entitymanagement.v1.projects.users.permissions.destroy
      summary: Revoke a specific permission from a user on a project.
      tags:
        - Project
      parameters:
        - name: project
          in: path
          required: true
          description: The project ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: permission
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        enum:
                          - Permission revoked successfully.
                          - Permission not found.
                      revoked:
                        type: boolean
                    required:
                      - message
                      - revoked
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /auth/v1/register:
    post:
      operationId: auth.v1.register
      description: Rate-limited by IP. May require a reCAPTCHA token.
      summary: Create a new local account
      tags:
        - RegistrationV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      requiresVerification:
                        type: string
                      verificationEmailSent:
                        type: boolean
                    required:
                      - requiresVerification
                      - verificationEmailSent
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '429':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: too_many_attempts
                      message:
                        type: string
                        const: >-
                          Too many registration attempts. Please try again
                          later.
                      details:
                        type: object
                        properties:
                          retry_after:
                            type: integer
                        required:
                          - retry_after
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Registration failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /auth/v1/check-email:
    post:
      operationId: auth.v1.check-email
      summary: Check whether an email is available for registration
      tags:
        - RegistrationV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckEmailV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      available:
                        type: boolean
                    required:
                      - available
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '429':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: too_many_attempts
                      message:
                        type: string
                        const: Too many requests. Please try again later.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Email check failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /auth/v1/providers:
    get:
      operationId: auth.v1.providers
      summary: List available authentication providers
      tags:
        - RegistrationV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      local:
                        type: string
                      oauth:
                        type: array
                        items: {}
                      recaptcha:
                        type: object
                        properties:
                          enabled:
                            type: boolean
                          siteKey:
                            type:
                              - string
                              - 'null'
                        required:
                          - enabled
                          - siteKey
                    required:
                      - local
                      - oauth
                      - recaptcha
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to retrieve providers.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /auth/v1/verify/{uuid}:
    get:
      operationId: auth.v1.verify
      description: >-
        Returns redirect URLs in the response body (consumer drives the
        redirect).
      summary: Verify an email address via token
      tags:
        - RegistrationV1
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      verified:
                        type: boolean
                      redirectUrl:
                        type: string
                    required:
                      - verified
                      - redirectUrl
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                        const: Email verification failed.
                      details:
                        type: object
                        properties:
                          redirectUrl:
                            type: string
                        required:
                          - redirectUrl
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Email verification failed. Please try again.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /auth/v1/resend-verification:
    post:
      operationId: auth.v1.resend-verification
      description: Always returns success to prevent email enumeration.
      summary: Resend the verification email
      tags:
        - RegistrationV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendVerificationV1Request'
      responses:
        '200':
          description: Always return success to prevent email enumeration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sent:
                        type: boolean
                    required:
                      - sent
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '429':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: too_many_attempts
                      message:
                        type: string
                        const: Too many requests. Please try again later.
                      details:
                        type: object
                        properties:
                          retry_after:
                            type: integer
                        required:
                          - retry_after
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: Failed to resend verification email.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
      security: []
  /entitypermissions/v1/roles:
    get:
      operationId: entitypermissions.v1.roles.index
      summary: List available global roles
      tags:
        - RoleCatalogV1
      parameters:
        - name: entity_type
          in: query
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RoleCatalogV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                        required:
                          - total
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /scopes/v1:
    get:
      operationId: scopes.v1.index
      tags:
        - ScopeV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      requiresScope:
                        anyOf:
                          - type: string
                          - type: boolean
                      activeScope:
                        type:
                          - object
                          - 'null'
                        properties:
                          scopeId:
                            type:
                              - string
                              - 'null'
                          type:
                            type:
                              - string
                              - 'null'
                          id:
                            type: string
                          name:
                            type: string
                          avatarUrl:
                            type: string
                        required:
                          - scopeId
                          - type
                          - id
                          - name
                          - avatarUrl
                    required:
                      - requestId
                      - requiresScope
                      - activeScope
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      summary: List scopes
  /scoring/v1:
    delete:
      operationId: scoring.v1.bulk-destroy
      summary: Bulk delete scoring records by id.
      tags:
        - ScoringV1
      parameters:
        - name: ids[]
          in: query
          schema:
            type: array
            items:
              type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
    get:
      operationId: scoring.v1.index
      summary: List scoring records for the current tenant.
      tags:
        - ScoringV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScoringResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: scoring.v1.store
      description: >-
        - On a successful (200/201) response from the provider: persists a score
          record and returns the score data with a 201 status.
        - On a 4xx response from the provider: returns a bad_request error
        envelope
          containing the provider's error body.
        - If the provider is unreachable or returns an unexpected status:
        returns a
          server_error envelope.
      summary: >-
        Run a credit score check via the scoring provider and persist the
        result.
      tags:
        - ScoringV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreScoringRequest'
      responses:
        '200':
          description: >-
            Provider returned a 4xx — surface the body as a bad_request
            envelope.
          content:
            application/json:
              schema:
                type: string
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      approved:
                        type: string
                      grossAmount:
                        type: string
                      companyName:
                        type: string
                      currency:
                        type: string
                    required:
                      - approved
                      - grossAmount
                      - companyName
                      - currency
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: server_error
                      message:
                        type: string
                        const: >-
                          An unexpected error occurred while processing the
                          scoring request.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /scoring/v1/{id}:
    delete:
      operationId: scoring.v1.destroy
      summary: Delete a single scoring record.
      tags:
        - ScoringV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /clients/v1/health:
    get:
      operationId: clients.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /cases/v1/health:
    get:
      operationId: cases.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /entitymanagement/v1/health:
    get:
      operationId: entitymanagement.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /company/v1/health:
    get:
      operationId: company.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /scoring/v1/health:
    get:
      operationId: scoring.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /scopes/v1/health:
    get:
      operationId: scopes.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /accounttracking/v1/health:
    get:
      operationId: accounttracking.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /entitypermissions/v1/health:
    get:
      operationId: entitypermissions.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /datasets/v1/health:
    get:
      operationId: datasets.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /bank/v1/health:
    get:
      operationId: bank.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /auth/v1/health:
    get:
      operationId: auth.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /users/v1/health:
    get:
      operationId: users.v1.health
      tags:
        - ServiceHealth
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
      security: []
      summary: Health
  /accounttracking/v1/accounts/discover:
    post:
      operationId: accounttracking.v1.accounts.discover
      description: >-
        Initiate a bank-account discovery session with the connected banking
        integration.

        Returns an opaque session object.


        This endpoint does not support the Idempotency-Key header.
      summary: Start a bank-account discovery session
      tags:
        - SessionV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoverAccountsV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: string
                  - type: object
                    properties:
                      data:
                        type: object
                        description: >-
                          Note: Integration-specific session tracking is now
                          handled by integration layer

                          via Phase 2 architecture (consent-session bindings,
                          etc.)

                          Return session info and any redirect URL
                        properties:
                          session_uuid:
                            type: string
                          redirect_url:
                            type:
                              - string
                              - 'null'
                          requires_redirect:
                            type: boolean
                          bank_name:
                            type:
                              - string
                              - 'null'
                          status:
                            type: string
                        required:
                          - session_uuid
                          - redirect_url
                          - requires_redirect
                          - bank_name
                          - status
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/sessions/{sessionUuid}/accounts:
    get:
      operationId: accounttracking.v1.sessions.accounts
      description: |-
        List accounts available within a discovery session.
        Returns the raw session account list from the provider.
      summary: List accounts in a discovery session
      tags:
        - SessionV1
      parameters:
        - name: sessionUuid
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: string
                  - type: object
                    properties:
                      data:
                        type: object
                        additionalProperties: {}
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                          pagination:
                            type: object
                            properties:
                              total:
                                type: integer
                              perPage:
                                type: integer
                              currentPage:
                                type: integer
                                const: 1
                              lastPage:
                                type: integer
                                const: 1
                            required:
                              - total
                              - perPage
                              - currentPage
                              - lastPage
                        required:
                          - requestId
                          - pagination
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /accounttracking/v1/sessions/{sessionUuid}/track:
    post:
      operationId: accounttracking.v1.sessions.track
      description: |-
        Track selected accounts from a discovery session.
        Returns 201 on success.
      summary: Track selected accounts from a session
      tags:
        - SessionV1
      parameters:
        - name: sessionUuid
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackSessionAccountsV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: >-
                      Don't mark session as completed - keep it active for
                      potential additional tracking
                    properties:
                      tracked_accounts:
                        type: array
                        items:
                          $ref: '#/components/schemas/TrackedAccount'
                      consent_ids:
                        type: array
                        items:
                          type: integer
                      session_status:
                        type: string
                      session_remains_active:
                        type: boolean
                      transaction_sync_jobs_dispatched:
                        type: integer
                      new_accounts_created:
                        type: integer
                      existing_accounts_reused:
                        type: integer
                    required:
                      - tracked_accounts
                      - consent_ids
                      - session_status
                      - session_remains_active
                      - transaction_sync_jobs_dispatched
                      - new_accounts_created
                      - existing_accounts_reused
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /productmanagement/v1/subscriptions:
    get:
      operationId: productmanagement.v1.subscriptions.index
      description: GET productmanagement/v1/subscriptions
      summary: List the current entity scope's active package subscriptions
      tags:
        - SubscriptionV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubscriptionV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: productmanagement.v1.subscriptions.store
      description: POST productmanagement/v1/subscriptions
      summary: Create a subscription for the current entity scope.
      tags:
        - SubscriptionV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeV1Request'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /productmanagement/v1/subscriptions/current:
    get:
      operationId: productmanagement.v1.subscriptions.current
      description: GET productmanagement/v1/subscriptions/current
      summary: Return the single current tier subscription for the scope, or null
      tags:
        - SubscriptionV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/SubscriptionV1Resource'
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: object
                    properties:
                      data:
                        type: 'null'
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    delete:
      operationId: productmanagement.v1.subscriptions.destroy-current
      description: DELETE productmanagement/v1/subscriptions/current
      summary: Cancel the current tier subscription for the scope
      tags:
        - SubscriptionV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /productmanagement/v1/subscriptions/{id}:
    delete:
      operationId: productmanagement.v1.subscriptions.destroy
      description: DELETE productmanagement/v1/subscriptions/{id}
      summary: Cancel a specific subscription by id
      tags:
        - SubscriptionV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /entitymanagement/v1/teams:
    get:
      operationId: entitymanagement.v1.teams.index
      description: >-
        Subscription gate: team.view requires the 'team'
        entity_service_subscription

        on the tenant. Returns 403 (not empty list) when the feature is
        unavailable

        so the client knows this tier does not include Teams.


        Visibility: tenant-wide viewers (admin/owner role on the tenant) see all

        teams. Team managers and members see only teams that GlobalAccessControl

        considers visible to them (they have a relationship with the team).
      summary: List teams visible to the authenticated user in the current scope
      tags:
        - Team
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamResource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    post:
      operationId: entitymanagement.v1.teams.store
      summary: Create a new team in the current tenant scope.
      tags:
        - Team
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreTeamRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type: string
                      metadata:
                        type: string
                      isActive:
                        type: string
                      createdBy:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - metadata
                      - isActive
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: An error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error overview.
                    example: Teams must be created at tenant scope
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/teams/{group}:
    get:
      operationId: entitymanagement.v1.teams.show
      summary: Show a single team.
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type: string
                      metadata:
                        type: string
                      isActive:
                        type: string
                      createdBy:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      memberCount:
                        type: integer
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - metadata
                      - isActive
                      - createdBy
                      - createdAt
                      - updatedAt
                      - memberCount
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    put:
      operationId: entitymanagement.v1.teams.update
      summary: Update a team (PUT = full replace, PATCH = partial).
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type: string
                      metadata:
                        type: string
                      isActive:
                        type: string
                      createdBy:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - metadata
                      - isActive
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    patch:
      operationId: entitymanagement.v1.teams.patch
      summary: Update a team (PUT = full replace, PATCH = partial).
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type: string
                      metadata:
                        type: string
                      isActive:
                        type: string
                      createdBy:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - name
                      - slug
                      - description
                      - metadata
                      - isActive
                      - createdBy
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: entitymanagement.v1.teams.destroy
      summary: Deactivate a team (sets is_active = false; no cascade delete).
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /entitymanagement/v1/teams/{group}/members:
    get:
      operationId: entitymanagement.v1.teams.members.index
      summary: List members of a team.
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: >-
                            `id` is required by React Admin's getList validator
                            and the dataProvider

                            shape contract. Use the userId since members are
                            identified by user.
                        user_id:
                          type: integer
                        name:
                          type: string
                        email:
                          type: string
                        member_role:
                          type: string
                          description: >-
                            `member_role` is what the UI shows in the role
                            column. Map the

                            team-internal role (team-manager → 'manager') back
                            to the UI vocabulary

                            the addMember endpoint accepts.
                          enum:
                            - manager
                            - member
                        role:
                          type: string
                        roles:
                          type: array
                          description: deprecated single-value field (see roles)
                          items: {}
                        permissions:
                          type: array
                          items:
                            type: string
                        permission_count:
                          type: integer
                        established_at:
                          type: string
                          format: date-time
                      required:
                        - id
                        - user_id
                        - name
                        - email
                        - member_role
                        - role
                        - roles
                        - permissions
                        - permission_count
                        - established_at
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: entitymanagement.v1.teams.members.store
      summary: Add a member to a team.
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTeamMemberRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Member added successfully.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/teams/{group}/members/{userId}:
    delete:
      operationId: entitymanagement.v1.teams.members.destroy
      summary: Remove a member from a team.
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /entitymanagement/v1/teams/{group}/roles:
    get:
      operationId: entitymanagement.v1.teams.roles.index
      summary: List roles assigned to the team as a polymorphic actor.
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            React Admin / dataProvider getList contract: items
                            need an `id`.

                            Use role_key — it's unique per team+target tuple.
                        role:
                          type: string
                        role_name:
                          type: string
                        capabilities:
                          type: array
                          items: {}
                        key:
                          type: string
                        type:
                          type: string
                          description: deprecated alias of role_key
                        target_entity_type:
                          type: string
                        target_entity_id:
                          type: string
                        assigned_at:
                          type: string
                          format: date-time
                        assigned_by:
                          type:
                            - integer
                            - 'null'
                        expires_at:
                          type:
                            - string
                            - 'null'
                          format: date-time
                      required:
                        - id
                        - role
                        - role_name
                        - capabilities
                        - key
                        - type
                        - target_entity_type
                        - target_entity_id
                        - assigned_at
                        - assigned_by
                        - expires_at
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
    post:
      operationId: entitymanagement.v1.teams.roles.store
      summary: Assign a role to the team as a polymorphic actor on a target entity.
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignTeamRoleRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Role assigned to team.
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
  /entitymanagement/v1/teams/{group}/roles/{role}:
    delete:
      operationId: entitymanagement.v1.teams.roles.destroy
      summary: Revoke a role from the team.
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: role
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        enum:
                          - Role revoked from team.
                          - Role not found on team.
                      revoked:
                        type: boolean
                    required:
                      - message
                      - revoked
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /entitymanagement/v1/teams/{group}/effective-permissions:
    get:
      operationId: entitymanagement.v1.teams.effective-permissions
      description: |-
        Returns the permissions the user has at the team's tenant scope
        (inherited via the team's polymorphic role assignments).

        Route middleware: entity.permission:group,team.view
      summary: List effective permissions for the authenticated user via this team
      tags:
        - Team
      parameters:
        - name: group
          in: path
          required: true
          description: The group ID
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        capability:
                          type: string
                        source:
                          type: string
                          const: team
                      required:
                        - id
                        - capability
                        - source
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      teamId:
                        type: string
                      teamRoles:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: >-
                                React Admin / dataProvider getList contract:
                                items need an `id`.

                                Use role_key — it's unique per team+target
                                tuple.
                            role:
                              type: string
                            role_name:
                              type: string
                            capabilities:
                              type: array
                              items: {}
                            key:
                              type: string
                            type:
                              type: string
                              description: deprecated alias of role_key
                            target_entity_type:
                              type: string
                            target_entity_id:
                              type: string
                            assigned_at:
                              type: string
                              format: date-time
                            assigned_by:
                              type:
                                - integer
                                - 'null'
                            expires_at:
                              type:
                                - string
                                - 'null'
                              format: date-time
                          required:
                            - id
                            - role
                            - role_name
                            - capabilities
                            - key
                            - type
                            - target_entity_type
                            - target_entity_id
                            - assigned_at
                            - assigned_by
                            - expires_at
                      permissionCount:
                        type: integer
                    required:
                      - requestId
                      - teamId
                      - teamRoles
                      - permissionCount
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
  /accounttracking/v1/transactions/{transaction}/bind-counterpart:
    post:
      operationId: accounttracking.v1.transactions.bind-counterpart
      description: |-
        Bind a transaction to a counterpart entity.
        Returns 201 + CounterpartV1Resource.
      summary: Bind a transaction to a counterpart entity
      tags:
        - TransactionCounterpartV1
      parameters:
        - name: transaction
          in: path
          required: true
          description: The transaction ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                counterpartId:
                  type: integer
              required:
                - counterpartId
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bind_failed
                      message:
                        type: string
                        const: Failed to bind transaction to counterpart
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/transactions/{transaction}/unbind-counterpart:
    delete:
      operationId: accounttracking.v1.transactions.unbind-counterpart
      description: |-
        Unbind a transaction from its counterpart.
        Returns 204 No Content.
      summary: Unbind a transaction from its counterpart
      tags:
        - TransactionCounterpartV1
      parameters:
        - name: transaction
          in: path
          required: true
          description: The transaction ID
          schema:
            type: integer
        - name: counterpartEntityId
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_bound
                      message:
                        type: string
                        const: Transaction is not bound to any counterpart
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: unbind_failed
                      message:
                        type: string
                        const: Failed to unbind transaction from counterpart
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/transactions/{transaction}/counterpart:
    get:
      operationId: accounttracking.v1.transactions.counterpart
      description: Get the counterpart entity linked to a transaction.
      summary: Get the counterpart linked to a transaction
      tags:
        - TransactionCounterpartV1
      parameters:
        - name: transaction
          in: path
          required: true
          description: The transaction ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type: string
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: object
                    properties:
                      data:
                        type: 'null'
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: fetch_failed
                      message:
                        type: string
                        const: Failed to get transaction counterpart
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/transactions/{transaction}/counterpart-suggestions:
    get:
      operationId: accounttracking.v1.transactions.counterpart-suggestions
      description: Suggest counterparts for a transaction based on name/IBAN matching.
      summary: Suggest counterparts for a transaction by name/IBAN match
      tags:
        - TransactionCounterpartV1
      parameters:
        - name: transaction
          in: path
          required: true
          description: The transaction ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      suggestions:
                        type: array
                        items: {}
                    required:
                      - suggestions
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: suggestions_failed
                      message:
                        type: string
                        const: Failed to get counterpart suggestions
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/transactions/{transaction}/create-counterpart:
    post:
      operationId: accounttracking.v1.transactions.create-counterpart
      description: |-
        Auto-create a counterpart from a transaction and optionally bind.
        Returns 201 + CounterpartV1Resource.
      summary: Auto-create and optionally bind a counterpart from a transaction
      tags:
        - TransactionCounterpartV1
      parameters:
        - name: transaction
          in: path
          required: true
          description: The transaction ID
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                overrideIdentifier:
                  type:
                    - string
                    - 'null'
                  maxLength: 255
                autoBind:
                  type: boolean
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: create_failed
                      message:
                        type: string
                        const: >-
                          Could not create counterpart from transaction —
                          insufficient data
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: create_bind_failed
                      message:
                        type: string
                        const: Failed to create counterpart from transaction
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/accounts/{id}/transactions/forceupdate:
    post:
      operationId: accounttracking.v1.accounts.transactions.forceupdate
      description: |-
        Force-update transactions for an account from the provider.
        This endpoint does not support the Idempotency-Key header.
      summary: Force-refresh transactions for an account from the provider
      tags:
        - TransactionV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      job_dispatched:
                        type: boolean
                      from_date:
                        type: string
                      to_date:
                        type: string
                      force_refresh:
                        type: boolean
                      backfill_triggered:
                        type: boolean
                    required:
                      - job_dispatched
                      - from_date
                      - to_date
                      - force_refresh
                      - backfill_triggered
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: account_tracking_inactive
                      message:
                        type: string
                        const: User is NOT registered and active for Account Tracking
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/accounts/{id}/transactions:
    get:
      operationId: accounttracking.v1.accounts.transactions
      description: |-
        Cursor-paginated transaction list, ordered by booking date. Treat the
        cursor as an opaque string. Responses do not include an ETag.
      summary: List transactions for an account (cursor-paginated)
      tags:
        - TransactionV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
        - name: cursor
          in: query
          schema:
            type:
              - string
              - 'null'
        - name: filter[fromDate]
          in: query
          schema:
            type: string
            format: date
        - name: filter[toDate]
          in: query
          schema:
            type: string
            format: date
        - name: filter[scope]
          in: query
          schema:
            type: string
            enum:
              - organization
              - person
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      anyOf:
                        - type: object
                          properties:
                            id:
                              type: string
                            internalTransactionId:
                              type: string
                            bookingDate:
                              type: string
                            valueDate:
                              type: string
                            transactionAmount:
                              type: number
                            currencyCode:
                              type: string
                            sourceCurrency:
                              type: string
                            targetCurrency:
                              type: string
                            exchangeRate:
                              type:
                                - number
                                - 'null'
                            debtorIban:
                              type: string
                              description: Debtor information
                            debtorBban:
                              type: string
                            debtorName:
                              type: string
                            debtorBankName:
                              type: string
                            debtorRemittanceInformation:
                              type: string
                            creditorIban:
                              type: string
                              description: Creditor information
                            creditorBban:
                              type: string
                            creditorName:
                              type: string
                            creditorBankName:
                              type: string
                            creditorRemittanceInformation:
                              type: string
                            direction:
                              type: string
                              description: Processed fields
                            counterpartAccountNumber:
                              type: string
                            counterpartName:
                              type: string
                            remittanceInformation:
                              type: string
                            counterpartyBankName:
                              type: string
                            countryCode:
                              type: string
                            countryCodeConfidence:
                              type:
                                - number
                                - 'null'
                            countryCodeMethod:
                              type: string
                            transactionType:
                              type: string
                              description: >-
                                Deprecated transaction type alias (backward
                                compatibility)
                            canonicalType:
                              type: string
                              description: Enhanced classification information
                            canonicalTypeLabel:
                              type: string
                            canonicalSubtype:
                              type: string
                            canonicalChannel:
                              type: string
                            canonicalChannelLabel:
                              type: string
                            canonicalScheme:
                              type: string
                            canonicalPurpose:
                              type: string
                            classificationConfidence:
                              type:
                                - number
                                - 'null'
                              description: Classification metadata
                            classificationMethod:
                              type: string
                            classificationCountry:
                              type: string
                            classificationProvider:
                              type: string
                            merchantCategoryCode:
                              type: string
                              description: Additional transaction metadata
                            transactionStatus:
                              type: string
                            transactionMetadata:
                              type: string
                              description: >-
                                Parser-extracted transaction facts
                                (merchant_city, terminal_id,

                                receipt_number, card_masked, wallet_device,
                                etc.).
                            mandateId:
                              type: string
                              description: >-
                                Additional database fields for backward
                                compatibility
                            referenceNumber:
                              type: string
                            isReversal:
                              type: boolean
                            counterpartType:
                              description: Counterpart classification fields
                              anyOf:
                                - type: string
                                - type: string
                                  enum:
                                    - other
                            counterpartTypeLabel:
                              anyOf:
                                - type: string
                                - type: string
                                  enum:
                                    - Other
                            counterpartTypeConfidence:
                              type:
                                - number
                                - 'null'
                            counterpartTypeMethod:
                              type: string
                            companyId:
                              type: string
                              description: Company relationship fields
                            counterpartEntityId:
                              type: string
                            company_id:
                              type: string
                            company:
                              type:
                                - object
                                - 'null'
                              description: Deprecated snake_case alias
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                organization_number:
                                  type:
                                    - string
                                    - 'null'
                              required:
                                - id
                                - name
                                - organization_number
                            company_binding_source:
                              type: string
                            company_binding_confidence:
                              type:
                                - number
                                - 'null'
                            company_bound_at:
                              type: string
                            company_bound_by:
                              type: string
                            isCardTransaction:
                              type: string
                              description: Computed classification flags
                            isInstantPayment:
                              type: string
                            isFee:
                              type: string
                            isTransfer:
                              type: string
                            hasHighConfidence:
                              type: string
                            needsReclassification:
                              type: string
                            hasCounterpartClassification:
                              type: string
                            hasHighCounterpartConfidence:
                              type: string
                            needsCounterpartClassification:
                              type: string
                            counterpart:
                              type:
                                - object
                                - 'null'
                              description: Counterpart entity information
                              properties:
                                id:
                                  type: string
                                counterpart_name:
                                  type: string
                                display_name:
                                  type: string
                                user_alias:
                                  type: string
                                user_alias_notes:
                                  type: string
                                effective_name:
                                  type: string
                                has_user_alias:
                                  type: boolean
                                type:
                                  type: string
                                country_code:
                                  type: string
                                is_root:
                                  type: string
                                direct_counterpart:
                                  type: object
                                  properties:
                                    id:
                                      type: integer
                                    counterpart_name:
                                      type:
                                        - string
                                        - 'null'
                                    display_name:
                                      type:
                                        - string
                                        - 'null'
                                  required:
                                    - id
                                    - counterpart_name
                                    - display_name
                              required:
                                - id
                                - counterpart_name
                                - display_name
                                - user_alias
                                - user_alias_notes
                                - effective_name
                                - has_user_alias
                                - type
                                - country_code
                                - is_root
                                - direct_counterpart
                          required:
                            - id
                            - internalTransactionId
                            - bookingDate
                            - valueDate
                            - transactionAmount
                            - currencyCode
                            - sourceCurrency
                            - targetCurrency
                            - exchangeRate
                            - debtorIban
                            - debtorBban
                            - debtorName
                            - debtorBankName
                            - debtorRemittanceInformation
                            - creditorIban
                            - creditorBban
                            - creditorName
                            - creditorBankName
                            - creditorRemittanceInformation
                            - direction
                            - counterpartAccountNumber
                            - counterpartName
                            - remittanceInformation
                            - counterpartyBankName
                            - countryCode
                            - countryCodeConfidence
                            - countryCodeMethod
                            - transactionType
                            - canonicalType
                            - canonicalTypeLabel
                            - canonicalSubtype
                            - canonicalChannel
                            - canonicalChannelLabel
                            - canonicalScheme
                            - canonicalPurpose
                            - classificationConfidence
                            - classificationMethod
                            - classificationCountry
                            - classificationProvider
                            - merchantCategoryCode
                            - transactionStatus
                            - transactionMetadata
                            - mandateId
                            - referenceNumber
                            - isReversal
                            - counterpartType
                            - counterpartTypeLabel
                            - counterpartTypeConfidence
                            - counterpartTypeMethod
                            - companyId
                            - counterpartEntityId
                            - company_id
                            - company
                            - company_binding_source
                            - company_binding_confidence
                            - company_bound_at
                            - company_bound_by
                            - isCardTransaction
                            - isInstantPayment
                            - isFee
                            - isTransfer
                            - hasHighConfidence
                            - needsReclassification
                            - hasCounterpartClassification
                            - hasHighCounterpartConfidence
                            - needsCounterpartClassification
                            - counterpart
                        - type: object
                          properties:
                            id:
                              type: string
                              description: Core identifiers
                            transactionId:
                              type: string
                            internalTransactionId:
                              type: string
                              description: alias of partner_transaction_id
                            physicalAccountId:
                              type: string
                            transactionAmount:
                              type: number
                              description: >-
                                Amounts / currency (both canonical names +
                                backward aliases)
                            amount:
                              type: number
                            signedAmount:
                              type: string
                              description: alias — kept for old consumers
                            currencyCode:
                              type: string
                            currency:
                              type: string
                            sourceCurrency:
                              type: string
                              description: alias — kept for old consumers
                            targetCurrency:
                              type: string
                            exchangeRate:
                              type:
                                - number
                                - 'null'
                            bookingDate:
                              type: string
                              description: Dates (Y-m-d strings — NOT ISO-8601 timestamps)
                            valueDate:
                              type: string
                            debtorIban:
                              type: string
                              description: Debtor
                            debtorBban:
                              type: string
                            debtorName:
                              type: string
                            debtorBankName:
                              type: string
                            debtorRemittanceInformation:
                              type: string
                            creditorIban:
                              type: string
                              description: Creditor
                            creditorBban:
                              type: string
                            creditorName:
                              type: string
                            creditorBankName:
                              type: string
                            creditorRemittanceInformation:
                              type: string
                            direction:
                              type: string
                              description: Processed / counterpart fields
                            counterpartAccountNumber:
                              type: string
                            counterpartName:
                              type: string
                            remittanceInformation:
                              type: string
                            description:
                              type: string
                            counterpartyBankName:
                              type: string
                              description: alias
                            countryCode:
                              type: string
                            countryCodeConfidence:
                              type:
                                - number
                                - 'null'
                            countryCodeMethod:
                              type: string
                            transactionType:
                              type: string
                              description: Transaction type (deprecated alias + canonical)
                            type:
                              type: string
                              description: alias
                            canonicalType:
                              type: string
                              description: |-
                                alias
                                Enhanced classification
                            canonicalTypeLabel:
                              type: string
                            canonicalSubtype:
                              type: string
                            canonicalChannel:
                              type: string
                            canonicalChannelLabel:
                              type: string
                            canonicalScheme:
                              type: string
                            canonicalPurpose:
                              type: string
                            classificationConfidence:
                              type:
                                - number
                                - 'null'
                            classificationMethod:
                              type: string
                            classificationCountry:
                              type: string
                            classificationProvider:
                              type: string
                            merchantCategoryCode:
                              type: string
                              description: Additional metadata
                            transactionStatus:
                              type: string
                            status:
                              type: string
                            transactionMetadata:
                              type: string
                              description: alias
                            mandateId:
                              type: string
                            referenceNumber:
                              type: string
                            isReversal:
                              type: boolean
                            counterpartType:
                              description: Counterpart classification
                              anyOf:
                                - type: string
                                - type: string
                                  enum:
                                    - other
                            counterpartTypeLabel:
                              anyOf:
                                - type: string
                                - type: string
                                  enum:
                                    - Other
                            counterpartTypeConfidence:
                              type:
                                - number
                                - 'null'
                            counterpartTypeMethod:
                              type: string
                            companyId:
                              type: string
                              description: Company binding (camelCase only — v1 contract)
                            company:
                              type:
                                - object
                                - 'null'
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                organizationNumber:
                                  type:
                                    - string
                                    - 'null'
                              required:
                                - id
                                - name
                                - organizationNumber
                            companyBindingSource:
                              type: string
                            companyBindingConfidence:
                              type:
                                - number
                                - 'null'
                            companyBoundAt:
                              type:
                                - string
                                - 'null'
                            companyBoundBy:
                              type: string
                            counterpartEntityId:
                              type: string
                              description: Counterpart entity
                            counterpart:
                              type:
                                - object
                                - 'null'
                              properties:
                                id:
                                  type: string
                                counterpartName:
                                  type: string
                                displayName:
                                  type: string
                                effectiveName:
                                  type: string
                                userAlias:
                                  type: string
                                userAliasNotes:
                                  type: string
                                hasUserAlias:
                                  type: boolean
                                type:
                                  type:
                                    - string
                                    - 'null'
                                countryCode:
                                  type: string
                                isRoot:
                                  type: string
                                directCounterpart:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    counterpartName:
                                      type: string
                                    displayName:
                                      type: string
                                  required:
                                    - id
                                    - counterpartName
                                    - displayName
                              required:
                                - id
                                - counterpartName
                                - displayName
                                - effectiveName
                                - userAlias
                                - userAliasNotes
                                - hasUserAlias
                                - type
                                - countryCode
                                - isRoot
                                - directCounterpart
                            isCardTransaction:
                              type: string
                              description: Computed classification flags
                            isInstantPayment:
                              type: string
                            isFee:
                              type: string
                            isTransfer:
                              type: string
                            hasHighConfidence:
                              type: string
                            needsReclassification:
                              type: string
                            hasCounterpartClassification:
                              type: string
                            hasHighCounterpartConfidence:
                              type: string
                            needsCounterpartClassification:
                              type: string
                            boundCompanyId:
                              type: string
                              description: >-
                                Backward-compat extras from controller
                                ->additional()
                            boundCompanyName:
                              type:
                                - string
                                - 'null'
                            raw:
                              type: string
                              description: >-
                                Raw provider data (opaque blob — verbatim, no
                                key transformation)
                            createdAt:
                              type:
                                - string
                                - 'null'
                              description: Timestamps (ISO-8601 UTC)
                            updatedAt:
                              type:
                                - string
                                - 'null'
                          required:
                            - id
                            - transactionId
                            - internalTransactionId
                            - physicalAccountId
                            - transactionAmount
                            - amount
                            - signedAmount
                            - currencyCode
                            - currency
                            - sourceCurrency
                            - targetCurrency
                            - exchangeRate
                            - bookingDate
                            - valueDate
                            - debtorIban
                            - debtorBban
                            - debtorName
                            - debtorBankName
                            - debtorRemittanceInformation
                            - creditorIban
                            - creditorBban
                            - creditorName
                            - creditorBankName
                            - creditorRemittanceInformation
                            - direction
                            - counterpartAccountNumber
                            - counterpartName
                            - remittanceInformation
                            - description
                            - counterpartyBankName
                            - countryCode
                            - countryCodeConfidence
                            - countryCodeMethod
                            - transactionType
                            - type
                            - canonicalType
                            - canonicalTypeLabel
                            - canonicalSubtype
                            - canonicalChannel
                            - canonicalChannelLabel
                            - canonicalScheme
                            - canonicalPurpose
                            - classificationConfidence
                            - classificationMethod
                            - classificationCountry
                            - classificationProvider
                            - merchantCategoryCode
                            - transactionStatus
                            - status
                            - transactionMetadata
                            - mandateId
                            - referenceNumber
                            - isReversal
                            - counterpartType
                            - counterpartTypeLabel
                            - counterpartTypeConfidence
                            - counterpartTypeMethod
                            - companyId
                            - company
                            - companyBindingSource
                            - companyBindingConfidence
                            - companyBoundAt
                            - companyBoundBy
                            - counterpartEntityId
                            - counterpart
                            - isCardTransaction
                            - isInstantPayment
                            - isFee
                            - isTransfer
                            - hasHighConfidence
                            - needsReclassification
                            - hasCounterpartClassification
                            - hasHighCounterpartConfidence
                            - needsCounterpartClassification
                            - boundCompanyId
                            - boundCompanyName
                            - raw
                            - createdAt
                            - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      pagination:
                        type: object
                        properties:
                          perPage:
                            type:
                              - object
                              - 'null'
                          nextCursor:
                            type: string
                          prevCursor: {}
                        required:
                          - perPage
                          - nextCursor
                          - prevCursor
                    required:
                      - requestId
                      - pagination
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: account_tracking_inactive
                      message:
                        type: string
                        const: User is NOT registered and active for Account Tracking
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /accounttracking/v1/accounts/{accountId}/transactions/{transactionId}:
    get:
      operationId: accounttracking.v1.accounts.transactions.show
      description: Fetch a single transaction.
      summary: Fetch a single transaction
      tags:
        - TransactionV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: string
                          internalTransactionId:
                            type: string
                          bookingDate:
                            type: string
                          valueDate:
                            type: string
                          transactionAmount:
                            type: number
                          currencyCode:
                            type: string
                          sourceCurrency:
                            type: string
                          targetCurrency:
                            type: string
                          exchangeRate:
                            type:
                              - number
                              - 'null'
                          debtorIban:
                            type: string
                            description: Debtor information
                          debtorBban:
                            type: string
                          debtorName:
                            type: string
                          debtorBankName:
                            type: string
                          debtorRemittanceInformation:
                            type: string
                          creditorIban:
                            type: string
                            description: Creditor information
                          creditorBban:
                            type: string
                          creditorName:
                            type: string
                          creditorBankName:
                            type: string
                          creditorRemittanceInformation:
                            type: string
                          direction:
                            type: string
                            description: Processed fields
                          counterpartAccountNumber:
                            type: string
                          counterpartName:
                            type: string
                          remittanceInformation:
                            type: string
                          counterpartyBankName:
                            type: string
                          countryCode:
                            type: string
                          countryCodeConfidence:
                            type:
                              - number
                              - 'null'
                          countryCodeMethod:
                            type: string
                          transactionType:
                            type: string
                            description: >-
                              Deprecated transaction type alias (backward
                              compatibility)
                          canonicalType:
                            type: string
                            description: Enhanced classification information
                          canonicalTypeLabel:
                            type: string
                          canonicalSubtype:
                            type: string
                          canonicalChannel:
                            type: string
                          canonicalChannelLabel:
                            type: string
                          canonicalScheme:
                            type: string
                          canonicalPurpose:
                            type: string
                          classificationConfidence:
                            type:
                              - number
                              - 'null'
                            description: Classification metadata
                          classificationMethod:
                            type: string
                          classificationCountry:
                            type: string
                          classificationProvider:
                            type: string
                          merchantCategoryCode:
                            type: string
                            description: Additional transaction metadata
                          transactionStatus:
                            type: string
                          transactionMetadata:
                            type: string
                            description: >-
                              Parser-extracted transaction facts (merchant_city,
                              terminal_id,

                              receipt_number, card_masked, wallet_device, etc.).
                          mandateId:
                            type: string
                            description: >-
                              Additional database fields for backward
                              compatibility
                          referenceNumber:
                            type: string
                          isReversal:
                            type: boolean
                          counterpartType:
                            description: Counterpart classification fields
                            anyOf:
                              - type: string
                              - type: string
                                enum:
                                  - other
                          counterpartTypeLabel:
                            anyOf:
                              - type: string
                              - type: string
                                enum:
                                  - Other
                          counterpartTypeConfidence:
                            type:
                              - number
                              - 'null'
                          counterpartTypeMethod:
                            type: string
                          companyId:
                            type: string
                            description: Company relationship fields
                          counterpartEntityId:
                            type: string
                          company_id:
                            type: string
                          company:
                            type:
                              - object
                              - 'null'
                            description: Deprecated snake_case alias
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              organization_number:
                                type:
                                  - string
                                  - 'null'
                            required:
                              - id
                              - name
                              - organization_number
                          company_binding_source:
                            type: string
                          company_binding_confidence:
                            type:
                              - number
                              - 'null'
                          company_bound_at:
                            type: string
                          company_bound_by:
                            type: string
                          isCardTransaction:
                            type: string
                            description: Computed classification flags
                          isInstantPayment:
                            type: string
                          isFee:
                            type: string
                          isTransfer:
                            type: string
                          hasHighConfidence:
                            type: string
                          needsReclassification:
                            type: string
                          hasCounterpartClassification:
                            type: string
                          hasHighCounterpartConfidence:
                            type: string
                          needsCounterpartClassification:
                            type: string
                          counterpart:
                            type:
                              - object
                              - 'null'
                            description: Counterpart entity information
                            properties:
                              id:
                                type: string
                              counterpart_name:
                                type: string
                              display_name:
                                type: string
                              user_alias:
                                type: string
                              user_alias_notes:
                                type: string
                              effective_name:
                                type: string
                              has_user_alias:
                                type: boolean
                              type:
                                type: string
                              country_code:
                                type: string
                              is_root:
                                type: string
                              direct_counterpart:
                                type: object
                                properties:
                                  id:
                                    type: integer
                                  counterpart_name:
                                    type:
                                      - string
                                      - 'null'
                                  display_name:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - id
                                  - counterpart_name
                                  - display_name
                            required:
                              - id
                              - counterpart_name
                              - display_name
                              - user_alias
                              - user_alias_notes
                              - effective_name
                              - has_user_alias
                              - type
                              - country_code
                              - is_root
                              - direct_counterpart
                        required:
                          - id
                          - internalTransactionId
                          - bookingDate
                          - valueDate
                          - transactionAmount
                          - currencyCode
                          - sourceCurrency
                          - targetCurrency
                          - exchangeRate
                          - debtorIban
                          - debtorBban
                          - debtorName
                          - debtorBankName
                          - debtorRemittanceInformation
                          - creditorIban
                          - creditorBban
                          - creditorName
                          - creditorBankName
                          - creditorRemittanceInformation
                          - direction
                          - counterpartAccountNumber
                          - counterpartName
                          - remittanceInformation
                          - counterpartyBankName
                          - countryCode
                          - countryCodeConfidence
                          - countryCodeMethod
                          - transactionType
                          - canonicalType
                          - canonicalTypeLabel
                          - canonicalSubtype
                          - canonicalChannel
                          - canonicalChannelLabel
                          - canonicalScheme
                          - canonicalPurpose
                          - classificationConfidence
                          - classificationMethod
                          - classificationCountry
                          - classificationProvider
                          - merchantCategoryCode
                          - transactionStatus
                          - transactionMetadata
                          - mandateId
                          - referenceNumber
                          - isReversal
                          - counterpartType
                          - counterpartTypeLabel
                          - counterpartTypeConfidence
                          - counterpartTypeMethod
                          - companyId
                          - counterpartEntityId
                          - company_id
                          - company
                          - company_binding_source
                          - company_binding_confidence
                          - company_bound_at
                          - company_bound_by
                          - isCardTransaction
                          - isInstantPayment
                          - isFee
                          - isTransfer
                          - hasHighConfidence
                          - needsReclassification
                          - hasCounterpartClassification
                          - hasHighCounterpartConfidence
                          - needsCounterpartClassification
                          - counterpart
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: object
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Transaction not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Account not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: account_tracking_inactive
                      message:
                        type: string
                        const: User is NOT registered and active for Account Tracking
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/accounts/{accountId}/sync-transactions:
    post:
      operationId: accounttracking.v1.accounts.transactions.sync
      description: >-
        Sync transactions for an account.


        Async (background=true): dispatches a background sync job and returns
        202
          { "data": { "status": "queued", "accountId": N, "estimatedCompletion": "..." }, "meta": { ... } }

        Sync (background=false, default): runs inline and returns 200
          { "data": { "syncMode": "immediate", "syncedCount": N }, "meta": { ... } }

        This endpoint does not support the Idempotency-Key header.
      summary: Sync transactions for an account from the provider
      tags:
        - TransactionV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncTransactionsV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      syncMode:
                        type: string
                        const: immediate
                      syncedCount:
                        type: integer
                    required:
                      - syncMode
                      - syncedCount
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        const: queued
                      accountId:
                        type: integer
                      estimatedCompletion:
                        type: string
                    required:
                      - status
                      - accountId
                      - estimatedCompletion
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: sync_already_running
                      message:
                        type: string
                        const: >-
                          A transaction sync is already running for this
                          account.
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: sync_error
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/accounts/{accountId}/sync-status:
    get:
      operationId: accounttracking.v1.accounts.sync-status
      description: >-
        Current sync state for an account. Returns null data if no sync run
        exists.

        This endpoint does not return an ETag (the data is volatile).
      summary: Get the current sync status for an account
      tags:
        - TransactionV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          syncRunId:
                            type: string
                          status:
                            type: string
                          totalTransactions:
                            type: integer
                          transactionsSynced:
                            type: integer
                          detailsFetched:
                            type: integer
                          detailsFailed:
                            type: integer
                          detailsSkipped:
                            type: integer
                          progressPercent:
                            type: number
                          isRunning:
                            type: boolean
                          errorMessage:
                            type: string
                          startedAt:
                            type:
                              - string
                              - 'null'
                          completedAt:
                            type:
                              - string
                              - 'null'
                        required:
                          - syncRunId
                          - status
                          - totalTransactions
                          - transactionsSynced
                          - detailsFetched
                          - detailsFailed
                          - detailsSkipped
                          - progressPercent
                          - isRunning
                          - errorMessage
                          - startedAt
                          - completedAt
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
                  - type: object
                    properties:
                      data:
                        type: 'null'
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - data
                      - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/accounts/{accountId}/transaction-stats:
    get:
      operationId: accounttracking.v1.accounts.transaction-stats
      description: |-
        Transaction statistics for an account.
        Returns an ETag and Cache-Control: private for conditional requests.
      summary: Get transaction statistics for an account
      tags:
        - TransactionV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      total_transactions:
                        type: integer
                      incoming_count:
                        type: integer
                      outgoing_count:
                        type: integer
                      bound_to_companies:
                        type: integer
                      unbound_transactions:
                        type: integer
                      total_incoming_amount: {}
                      total_outgoing_amount: {}
                      avg_transaction_amount: {}
                      date_range:
                        type: object
                        properties:
                          earliest: {}
                          latest: {}
                        required:
                          - earliest
                          - latest
                    required:
                      - total_transactions
                      - incoming_count
                      - outgoing_count
                      - bound_to_companies
                      - unbound_transactions
                      - total_incoming_amount
                      - total_outgoing_amount
                      - avg_transaction_amount
                      - date_range
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '304':
          description: ''
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/accounts/{accountId}/auto-bind-transactions:
    post:
      operationId: accounttracking.v1.accounts.auto-bind-transactions
      description: Auto-bind transactions by counterpart name matching.
      summary: Auto-bind transactions by counterpart name matching
      tags:
        - TransactionV1
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      boundCount:
                        type: integer
                      message:
                        type: string
                    required:
                      - boundCount
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Account not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bind_error
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/transactions/{transactionId}/bind-company:
    post:
      operationId: accounttracking.v1.transactions.bind-company
      description: Bind a transaction to a company.
      summary: Bind a transaction to a company
      tags:
        - TransactionV1
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: integer
              required:
                - companyId
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Transaction successfully bound to company
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: bind_failed
                      message:
                        type: string
                        const: Failed to bind transaction to company
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Transaction not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
    delete:
      operationId: accounttracking.v1.transactions.unbind-company
      description: Unbind a transaction from a company.
      summary: Unbind a transaction from a company
      tags:
        - TransactionV1
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        const: Transaction successfully unbound from company
                    required:
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: unbind_failed
                      message:
                        type: string
                        const: Failed to unbind transaction from company
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Transaction not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /accounttracking/v1/transactions/{transactionId}/company-suggestions:
    get:
      operationId: accounttracking.v1.transactions.company-suggestions
      description: Suggest companies for a transaction based on counterpart name.
      summary: Suggest companies for a transaction by counterpart name
      tags:
        - TransactionV1
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: integer
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      suggestions:
                        type: array
                        items:
                          type: string
                    required:
                      - suggestions
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: Transaction not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /users/v1/me/invitations:
    get:
      operationId: users.v1.me.invitations.index
      description: Returns the authenticated user's pending invitations.
      summary: List the authenticated user's pending invitations
      tags:
        - UserInvitationV1
      parameters:
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: '`ApiCollection`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserInvitationV1Resource'
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
  /users/v1/me/invitations/{token}/accept:
    post:
      operationId: users.v1.me.invitations.accept
      description: |-
        Re-runnable: accepting an already-accepted invitation returns the
        current state without erroring.
      summary: Accept a pending membership invitation
      tags:
        - UserInvitationV1
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      parentEntityType:
                        type: string
                      parentEntityId:
                        type: string
                      childEntityType:
                        type: string
                      childEntityId:
                        type: string
                      relationshipType:
                        type: string
                      status:
                        type: string
                      invitationToken:
                        type: string
                      invitationTokenExpiresAt:
                        type:
                          - string
                          - 'null'
                      invitedAt:
                        type:
                          - string
                          - 'null'
                      acceptedAt:
                        type:
                          - string
                          - 'null'
                      rejectedAt:
                        type:
                          - string
                          - 'null'
                      suspendedAt:
                        type:
                          - string
                          - 'null'
                      invitedBy:
                        type: string
                      invitationMessage:
                        type: string
                      requestedRoleKey:
                        type: string
                      establishedBy:
                        type: string
                      establishedAt:
                        type:
                          - string
                          - 'null'
                      expiresAt:
                        type:
                          - string
                          - 'null'
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - parentEntityType
                      - parentEntityId
                      - childEntityType
                      - childEntityId
                      - relationshipType
                      - status
                      - invitationToken
                      - invitationTokenExpiresAt
                      - invitedAt
                      - acceptedAt
                      - rejectedAt
                      - suspendedAt
                      - invitedBy
                      - invitationMessage
                      - requestedRoleKey
                      - establishedBy
                      - establishedAt
                      - expiresAt
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: invitation_accept_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /users/v1/me/invitations/{token}/decline:
    post:
      operationId: users.v1.me.invitations.decline
      description: |-
        Re-runnable: declining an already-declined invitation returns the
        current state without erroring.
      summary: Decline a pending membership invitation
      tags:
        - UserInvitationV1
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      parentEntityType:
                        type: string
                      parentEntityId:
                        type: string
                      childEntityType:
                        type: string
                      childEntityId:
                        type: string
                      relationshipType:
                        type: string
                      status:
                        type: string
                      invitationToken:
                        type: string
                      invitationTokenExpiresAt:
                        type:
                          - string
                          - 'null'
                      invitedAt:
                        type:
                          - string
                          - 'null'
                      acceptedAt:
                        type:
                          - string
                          - 'null'
                      rejectedAt:
                        type:
                          - string
                          - 'null'
                      suspendedAt:
                        type:
                          - string
                          - 'null'
                      invitedBy:
                        type: string
                      invitationMessage:
                        type: string
                      requestedRoleKey:
                        type: string
                      establishedBy:
                        type: string
                      establishedAt:
                        type:
                          - string
                          - 'null'
                      expiresAt:
                        type:
                          - string
                          - 'null'
                      metadata:
                        type: string
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                    required:
                      - id
                      - parentEntityType
                      - parentEntityId
                      - childEntityType
                      - childEntityId
                      - relationshipType
                      - status
                      - invitationToken
                      - invitationTokenExpiresAt
                      - invitedAt
                      - acceptedAt
                      - rejectedAt
                      - suspendedAt
                      - invitedBy
                      - invitationMessage
                      - requestedRoleKey
                      - establishedBy
                      - establishedAt
                      - expiresAt
                      - metadata
                      - createdAt
                      - updatedAt
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: invitation_decline_failed
                      message:
                        type: string
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
  /users/v1/{id}/scope-profile:
    get:
      operationId: users.v1.scope-profile.show
      description: |-
        Read the user's profile as seen within the current scope, resolving in
        order: scope-specific, then ancestor scope, then default — so an unset
        scope profile gracefully falls back to the user's default profile.
      summary: Read the user's profile within the current scope
      tags:
        - UserProfileRolesV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type:
              - string
              - 'null'
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      defaultMetadata:
                        type:
                          - string
                          - 'null'
                      scopedMetadata:
                        type:
                          - string
                          - 'null'
                      mergedMetadata:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              type: string
                            minItems: 0
                            maxItems: 0
                            additionalItems: false
                      scope:
                        type:
                          - string
                          - 'null'
                      profile:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: string
                          displayName:
                            type:
                              - string
                              - 'null'
                          description:
                            type:
                              - string
                              - 'null'
                          logoPath:
                            type:
                              - string
                              - 'null'
                          avatarPath:
                            type: string
                          visibilityScope:
                            type: string
                          isActive:
                            type: string
                          scopeEntityType:
                            type: string
                          scopeEntityId:
                            type: string
                          createdAt:
                            type: string
                          updatedAt:
                            type: string
                        required:
                          - id
                          - displayName
                          - description
                          - logoPath
                          - avatarPath
                          - visibilityScope
                          - isActive
                          - scopeEntityType
                          - scopeEntityId
                          - createdAt
                          - updatedAt
                    required:
                      - defaultMetadata
                      - scopedMetadata
                      - mergedMetadata
                      - scope
                      - profile
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: scope_missing
                      message:
                        type: string
                        const: Scope not set
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: User not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
    put:
      operationId: users.v1.scope-profile.update
      description: |-
        Save the user's scope-specific profile metadata. This does not write
        any credentials.

        Authorization: self-update is always permitted; updating another
        user's profile requires the members.manage permission.
      summary: Update the user's scope-specific profile metadata
      tags:
        - UserProfileRolesV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type:
              - string
              - 'null'
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScopeProfileV1Request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      defaultMetadata:
                        type:
                          - string
                          - 'null'
                      scopedMetadata:
                        type:
                          - string
                          - 'null'
                      mergedMetadata:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              type: string
                            minItems: 0
                            maxItems: 0
                            additionalItems: false
                      scope:
                        type:
                          - string
                          - 'null'
                      profile:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: string
                          displayName:
                            type:
                              - string
                              - 'null'
                          description:
                            type:
                              - string
                              - 'null'
                          logoPath:
                            type:
                              - string
                              - 'null'
                          avatarPath:
                            type: string
                          visibilityScope:
                            type: string
                          isActive:
                            type: string
                          scopeEntityType:
                            type: string
                          scopeEntityId:
                            type: string
                          createdAt:
                            type: string
                          updatedAt:
                            type: string
                        required:
                          - id
                          - displayName
                          - description
                          - logoPath
                          - avatarPath
                          - visibilityScope
                          - isActive
                          - scopeEntityType
                          - scopeEntityId
                          - createdAt
                          - updatedAt
                    required:
                      - defaultMetadata
                      - scopedMetadata
                      - mergedMetadata
                      - scope
                      - profile
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: scope_missing
                      message:
                        type: string
                        const: Scope not set
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: User not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /users/v1/{id}/roles:
    post:
      operationId: users.v1.roles.assign
      description: |-
        Assign a role to a user on the current scope entity.

        Returns the updated user detail.
      summary: Assign a role to a user on the current scope entity
      tags:
        - UserProfileRolesV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type:
              - string
              - 'null'
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/App.Http.Requests.Users.V1.AssignRoleV1Request
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      firstName:
                        type:
                          - string
                          - 'null'
                      lastName:
                        type:
                          - string
                          - 'null'
                      email:
                        type: string
                      phone:
                        type:
                          - string
                          - 'null'
                      avatarUrl:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      membership:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: string
                          status:
                            type: string
                          invitedAt:
                            anyOf:
                              - type: 'null'
                              - type: string
                          acceptedAt:
                            anyOf:
                              - type: 'null'
                              - type: string
                          suspendedAt:
                            anyOf:
                              - type: 'null'
                              - type: string
                        required:
                          - id
                          - status
                          - invitedAt
                          - acceptedAt
                          - suspendedAt
                      roles:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            key:
                              type: string
                            name:
                              type: string
                            assignedAt:
                              anyOf:
                                - type: 'null'
                                - type: string
                            assignedBy:
                              type: string
                          required:
                            - id
                            - key
                            - name
                            - assignedAt
                            - assignedBy
                    required:
                      - id
                      - name
                      - firstName
                      - lastName
                      - email
                      - phone
                      - avatarUrl
                      - createdAt
                      - updatedAt
                      - membership
                      - roles
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: scope_missing
                      message:
                        type: string
                        const: Scope not set
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: not_found
                      message:
                        type: string
                        const: User not found
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '422':
          $ref: '#/components/responses/ValidationException'
  /users/v1/{id}/roles/{roleKey}:
    delete:
      operationId: users.v1.roles.revoke
      description: |-
        Revoke a role from a user on the current scope entity.

        Returns the updated user detail. If the role assignment does not
        exist, this returns a 404.
      summary: Revoke a role from a user on the current scope entity
      tags:
        - UserProfileRolesV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type:
              - string
              - 'null'
        - name: roleKey
          in: path
          required: true
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      firstName:
                        type:
                          - string
                          - 'null'
                      lastName:
                        type:
                          - string
                          - 'null'
                      email:
                        type: string
                      phone:
                        type:
                          - string
                          - 'null'
                      avatarUrl:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type:
                          - string
                          - 'null'
                      updatedAt:
                        type:
                          - string
                          - 'null'
                      membership:
                        type:
                          - object
                          - 'null'
                        properties:
                          id:
                            type: string
                          status:
                            type: string
                          invitedAt:
                            anyOf:
                              - type: 'null'
                              - type: string
                          acceptedAt:
                            anyOf:
                              - type: 'null'
                              - type: string
                          suspendedAt:
                            anyOf:
                              - type: 'null'
                              - type: string
                        required:
                          - id
                          - status
                          - invitedAt
                          - acceptedAt
                          - suspendedAt
                      roles:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            key:
                              type: string
                            name:
                              type: string
                            assignedAt:
                              anyOf:
                                - type: 'null'
                                - type: string
                            assignedBy:
                              type: string
                          required:
                            - id
                            - key
                            - name
                            - assignedAt
                            - assignedBy
                    required:
                      - id
                      - name
                      - firstName
                      - lastName
                      - email
                      - phone
                      - avatarUrl
                      - createdAt
                      - updatedAt
                      - membership
                      - roles
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - data
                  - meta
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: scope_missing
                      message:
                        type: string
                        const: Scope not set
                      details:
                        type: 'null'
                    required:
                      - code
                      - message
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                    required:
                      - requestId
                required:
                  - error
                  - meta
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: Role assignment not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: not_found
                          message:
                            type: string
                            const: User not found
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /users/v1:
    get:
      operationId: users.v1.index
      summary: List members of the active scope.
      tags:
        - UserV1
      parameters:
        - name: filter
          in: query
          schema:
            type: string
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
        - name: perPage
          in: query
          description: Items per page (default 25, max 100).
          schema:
            type: integer
        - name: sort
          in: query
          description: >-
            Comma-separated sort terms, e.g. `-createdAt,displayName`. Prefix a
            term with `-` for descending order. Only per-endpoint allowlisted
            fields are honoured; others are silently ignored.
          schema:
            type: string
        - name: filter[field]
          in: query
          description: >-
            Allowlisted field filter, e.g. `filter[status]=active`. Only
            per-endpoint allowlisted fields are honoured; others are silently
            ignored.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    delete:
      operationId: users.v1.destroy-multiple
      summary: Remove multiple members from the active scope. Body { ids }.
      tags:
        - UserV1
      parameters:
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '204':
          description: No content
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    const: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/MessageBag'
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: self_removal_forbidden
                          message:
                            type: string
                            const: You cannot remove yourself from this scope.
                          details:
                            type: 'null'
                        required:
                          - code
                          - message
                      meta:
                        type: object
                        properties:
                          requestId:
                            type: string
                        required:
                          - requestId
                    required:
                      - error
                      - meta
  /users/v1/{id}:
    get:
      operationId: users.v1.show
      summary: A member's detail within the active scope.
      tags:
        - UserV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type:
              - string
              - 'null'
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
    delete:
      operationId: users.v1.destroy
      summary: Remove a member from the active scope.
      tags:
        - UserV1
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type:
              - string
              - 'null'
        - name: X-Scope
          in: header
          required: true
          description: >-
            Operating scope for the request: the opaque `scopeId` string
            obtained from `GET /scopes/v1`. Send it exactly as returned — it is
            NOT an entity UUID and cannot be constructed by the client. Resolves
            the tenant/group/project the request operates within.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: string
        '204':
          description: No content
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    const: Scope not set
                required:
                  - message
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    const: User not found on this entity
                required:
                  - message
components:
  securitySchemes:
    http:
      type: http
      scheme: bearer
  schemas:
    AddAccountV1Request:
      type: object
      description: |-
        Validates the body of POST accounttracking/v1/accounts.

        Accepts camelCase external names; the controller maps to the
        internal AddAccountRequest DTO (bankId → bank_id, etc.).

        Authorization enforced by EntityPermissions in the controller.
      properties:
        bankId:
          type: string
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
        accountType:
          type: string
          enum:
            - private
            - company
            - payment
        visibility:
          type: object
          description: >-
            Optional visibility configuration (privacy-first — default:
            self-restricted)
          properties:
            shared:
              type: boolean
            visibleTo:
              type: object
              properties:
                type:
                  type: string
                id:
                  type: string
      required:
        - bankId
        - countryCode
        - accountType
      title: AddAccountV1Request
    AddGroupMemberRequest:
      type: object
      description: >-
        Validates add-member payload for groups.

        Authorization enforced by route middleware
        (entity.permission:group,members.invite).
      properties:
        userId:
          type: integer
        role:
          type: string
          enum:
            - member
            - owner
            - admin
      required:
        - userId
        - role
      title: AddGroupMemberRequest
    AddTeamMemberRequest:
      type: object
      description: >-
        Validates payload for adding a member to a Team.


        member_role determines the role assigned on the team:

        - 'member' (default): standard team member, no team management
        privileges.

        - 'manager': assigns the `team-manager` role on this team, granting
           team.view, team.update, team.manage_members on the team entity.

        Authorization for team.manage_members is enforced by route middleware.

        authorize() returns true per project convention (validation-only Form
        Requests).
      properties:
        userId:
          type: integer
        memberRole:
          type:
            - string
            - 'null'
          enum:
            - member
            - manager
      required:
        - userId
      title: AddTeamMemberRequest
    App.Http.Requests.Users.V1.AssignRoleV1Request:
      type: object
      description: |-
        Validates POST users/v1/{id}/roles.

        The role_key must reference a row in entity_roles — the exists rule
        enforces referential integrity at the application layer.

        Validation only — authorization is enforced in the controller via
        EntityPermissions::can('members.manage', $request).
      properties:
        role_key:
          type: string
      required:
        - role_key
      title: App.Http.Requests.Users.V1.AssignRoleV1Request
    AppKeyResource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        lastUsedAt:
          type:
            - string
            - 'null'
        expiresAt:
          type:
            - string
            - 'null'
        createdAt:
          type:
            - string
            - 'null'
      required:
        - id
        - name
        - lastUsedAt
        - expiresAt
        - createdAt
      title: AppKeyResource
    AppListResource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
        createdBy:
          type: string
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
        connectorId:
          type: string
        entity:
          type:
            - object
            - 'null'
          description: |-
            The entity this app is bound to (its member-edge parent) — lets
            the admin list show + link to the owning entity. Null if the app
            is somehow unparented. Per-row resolution (paginated list).
          properties:
            type:
              type: string
            id:
              type: string
            name:
              type:
                - string
                - 'null'
          required:
            - type
            - id
            - name
        hasClientCredentials:
          type: boolean
        delegated:
          type: boolean
          description: |-
            True when an active connection has delegated a user's visibility
            to this app, allowing it to act on that user's behalf within the
            connected scope.
        keysCount:
          type: string
        lastUsedAt:
          type:
            - string
            - 'null'
          description: |-
            Most-recent usage across all of the app's keys, eager-loaded via
            withMax('tokens', 'last_used_at') on the list query. The aggregate
            is a raw DB string (Laravel does not cast withMax results), so
            normalise before iso(); null when no key has ever been used.
      required:
        - id
        - name
        - description
        - status
        - createdBy
        - createdAt
        - updatedAt
        - connectorId
        - entity
        - hasClientCredentials
        - delegated
        - keysCount
        - lastUsedAt
      title: AppListResource
    AppRoleResource:
      type: object
      properties:
        roleKey:
          type: string
        roleName:
          type: string
        roleType:
          type: string
        entityType:
          type: string
        entityId:
          type: string
        assignedAt:
          type: string
      required:
        - roleKey
        - roleName
        - roleType
        - entityType
        - entityId
        - assignedAt
      title: AppRoleResource
    AssignProjectGroupRequest:
      type: object
      description: >-
        Validates assign-group payload for projects.

        Authorization enforced by route middleware
        (entity.permission:project,members.invite).
      properties:
        groupId:
          type: string
      required:
        - groupId
      title: AssignProjectGroupRequest
    AssignProjectUserRequest:
      type: object
      description: >-
        Validates assign-user payload for projects.

        Authorization enforced by route middleware
        (entity.permission:project,members.invite).
      properties:
        userId:
          type: integer
        role:
          type: string
          enum:
            - assigned
            - owner
            - collaborator
      required:
        - userId
        - role
      title: AssignProjectUserRequest
    AssignRoleV1Request:
      type: object
      properties:
        role_type:
          type: string
          enum:
            - standard
            - custom
        role_key:
          type: string
        options:
          type: object
          properties:
            expires_at:
              type:
                - string
                - 'null'
              format: date-time
            metadata:
              type:
                - array
                - 'null'
              items:
                type: string
            tenant_id:
              type:
                - integer
                - 'null'
      required:
        - role_type
        - role_key
      title: AssignRoleV1Request
    AssignTeamRoleRequest:
      type: object
      description: >-
        Validates payload for assigning a role to a Team as a polymorphic actor.


        The role grants the team (and through member inheritance) the capability
        bundle

        associated with that role on the target entity (defaults to the team's
        tenant).


        Authorization for team.assign_roles is enforced by route middleware.

        authorize() returns true per project convention (validation-only Form
        Requests).
      properties:
        role:
          type: string
          maxLength: 100
        roleType:
          type:
            - string
            - 'null'
          enum:
            - standard
            - custom
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - role
      title: AssignTeamRoleRequest
    AttachIntegrationV1Request:
      type: object
      description: >-
        V1 Form Request for POST
        productmanagement/v1/products/{slug}/integrations.


        Validation only — authorization is handled in the controller via
        EntityPermissions::authorize().

        Accepts camelCase `integrationId` (required UUID).
      properties:
        integrationId:
          type: string
          maxLength: 36
      required:
        - integrationId
      title: AttachIntegrationV1Request
    BankByBicV1Resource:
      anyOf:
        - type: object
          properties:
            banks:
              type: array
              items:
                $ref: '#/components/schemas/BankV1Resource'
            count:
              type: string
            bic:
              type: string
            country: {}
          required:
            - banks
            - count
            - bic
            - country
        - type: object
          properties:
            bank:
              $ref: '#/components/schemas/BankV1Resource'
            branchCount:
              type: string
          required:
            - bank
            - branchCount
      title: BankByBicV1Resource
    BankGetBankV1Resource:
      type: object
      properties:
        bank:
          $ref: '#/components/schemas/BankV1Resource'
        hasMultipleBranches:
          type: boolean
        branchCount:
          type: integer
      required:
        - bank
        - hasMultipleBranches
        - branchCount
      title: BankGetBankV1Resource
    BankIdentifyV1Resource:
      type: object
      properties:
        bank:
          $ref: '#/components/schemas/BankV1Resource'
        bic:
          type:
            - string
            - 'null'
        bankName:
          type: string
        bankIdentifier:
          type: string
        countryCode:
          type: string
        parsedIban:
          type: 'null'
      required:
        - bank
        - bic
        - bankName
        - bankIdentifier
        - countryCode
        - parsedIban
      title: BankIdentifyV1Resource
    BankShowV1Resource:
      type: object
      properties:
        bank:
          $ref: '#/components/schemas/BankV1Resource'
        branches:
          type: array
          items:
            type: string
        branchCount:
          type: integer
        hasMultipleBranches:
          type: boolean
      required:
        - bank
        - branches
        - branchCount
        - hasMultipleBranches
      title: BankShowV1Resource
    BankStatsV1Resource:
      type: object
      properties:
        summary:
          type: object
          properties:
            totalBanks:
              type: integer
            uniqueBics:
              type: integer
            uniqueBankNames:
              type: integer
            activeBanks:
              type: integer
          required:
            - totalBanks
            - uniqueBics
            - uniqueBankNames
            - activeBanks
        byCountry:
          type: array
          items:
            type: string
        topBanks:
          type: array
          items:
            type: string
        byProvider:
          type: array
          items:
            type: string
        filter:
          type: object
          properties:
            country: {}
          required:
            - country
      required:
        - summary
        - byCountry
        - topBanks
        - byProvider
        - filter
      title: BankStatsV1Resource
    BankV1Resource:
      type: object
      properties:
        id:
          type: integer
        bankIdentifier:
          type: string
        countryCode:
          type: string
        bic:
          type:
            - string
            - 'null'
        bankName:
          type: string
        slug:
          type:
            - string
            - 'null'
        fullIdentifier:
          type: string
        providerBankId:
          type:
            - string
            - 'null'
        providerName:
          type:
            - string
            - 'null'
        metadata:
          type:
            - array
            - 'null'
          items: {}
        providerData:
          type:
            - array
            - 'null'
          items: {}
        popularityRank:
          type:
            - integer
            - 'null'
        isActive:
          type: boolean
        logoUrl:
          type:
            - string
            - 'null'
        lastVerifiedAt:
          type:
            - string
            - 'null'
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - bankIdentifier
        - countryCode
        - bic
        - bankName
        - slug
        - fullIdentifier
        - providerBankId
        - providerName
        - metadata
        - providerData
        - popularityRank
        - isActive
        - logoUrl
        - lastVerifiedAt
        - createdAt
        - updatedAt
      title: BankV1Resource
    BindAccountV1Request:
      type: object
      description: >-
        Validates the body of POST accounttracking/v1/mappings/bind-account.


        Accepts camelCase external names. The controller maps these to the

        snake_case parameters expected by
        AccountEntityMappingService::createMapping().


        entityType validation (in:...) is done at service level via
        EntityTypeResolver;

        this request validates only shape and nullability.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        accountIdentifier:
          type: string
          maxLength: 50
        entityId:
          type: string
          maxLength: 50
        entityType:
          type: string
        ownershipType:
          type:
            - string
            - 'null'
          enum:
            - owner
            - authorized_signatory
            - joint_owner
        confidenceScore:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
        accessScope:
          type:
            - string
            - 'null'
          enum:
            - private
            - user
            - group
            - tenant
            - global
        countryCode:
          type:
            - string
            - 'null'
          minLength: 2
          maxLength: 2
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
      required:
        - accountIdentifier
        - entityId
        - entityType
      title: BindAccountV1Request
    BindEntityV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/counterparts/{counterpart}/bind-entity.


        Binds a company or entity record to the counterpart for enrichment.

        entityType must be a valid type from
        EntityTypeResolver::getAvailableEntityTypes().

        The controller validates the entity exists after binding.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        entityId:
          type: string
        entityType:
          type: string
      required:
        - entityId
        - entityType
      title: BindEntityV1Request
    BindTransactionToEntityV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/mappings/transactions/{transactionId}/bind-entity.


        Binds a transaction to a company or entity record for reporting
        purposes.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        entityId:
          type: string
        entityType:
          type: string
      required:
        - entityId
        - entityType
      title: BindTransactionToEntityV1Request
    BindTransactionsV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/counterparts/{counterpart}/bind-transactions.


        Bulk-binds a list of transaction IDs to the counterpart.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        transactionIds:
          type: array
          items:
            type: integer
            minimum: 1
          minItems: 1
      required:
        - transactionIds
      title: BindTransactionsV1Request
    CheckEmailV1Request:
      type: object
      description: >-
        Validation for POST auth/v1/check-email.


        Mirrors the inline validation from RegisterController::checkEmail().

        Authorization is always true — rate-limiting is handled in
        RegistrationV1Controller.
      properties:
        email:
          type: string
          format: email
          maxLength: 255
        entity_type:
          type: string
          maxLength: 50
      required:
        - email
      title: CheckEmailV1Request
    CheckPermissionBatchV1Request:
      type: object
      properties:
        user_id:
          type: integer
          minimum: 1
        entity_type:
          type: string
          enum:
            - user
            - tenant
            - group
            - project
            - client
            - case
            - consent
        entity_id:
          type: integer
          minimum: 1
        check_inheritance:
          type: boolean
        permissions:
          type: array
          items:
            type: string
          minItems: 1
      required:
        - user_id
        - entity_type
        - entity_id
        - permissions
      title: CheckPermissionBatchV1Request
    CheckPermissionV1Request:
      type: object
      properties:
        user_id:
          type: integer
          minimum: 1
        entity_type:
          type: string
          enum:
            - user
            - tenant
            - group
            - project
            - client
            - case
            - consent
        entity_id:
          type: integer
          minimum: 1
        permission:
          type: string
        check_inheritance:
          type: boolean
      required:
        - user_id
        - entity_type
        - entity_id
        - permission
      title: CheckPermissionV1Request
    ClientListResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        displayName:
          type: string
        countryCode:
          type: string
        registrationNumber:
          type:
            - string
            - 'null'
          description: Company fields — always declared; null when client is a person
        companySnapshot:
          anyOf:
            - type: object
              properties:
                registrationNumber:
                  type: string
                countryCode:
                  type: string
                country:
                  type:
                    - string
                    - 'null'
                vatNumber:
                  type:
                    - string
                    - 'null'
                name:
                  type: string
                tradingName:
                  type:
                    - string
                    - 'null'
                status:
                  type: string
                statusCode:
                  type:
                    - string
                    - 'null'
                legalForm:
                  type:
                    - string
                    - 'null'
                legalFormCode:
                  type:
                    - string
                    - 'null'
                registrationDate:
                  type: string
                incorporationDate:
                  type: string
                dissolutionDate:
                  type: string
                address:
                  type:
                    - object
                    - 'null'
                  properties:
                    street:
                      type:
                        - string
                        - 'null'
                    street2:
                      type:
                        - string
                        - 'null'
                    postalCode:
                      type:
                        - string
                        - 'null'
                    city:
                      type:
                        - string
                        - 'null'
                    region:
                      type:
                        - string
                        - 'null'
                    countryCode:
                      type:
                        - string
                        - 'null'
                    country:
                      type:
                        - string
                        - 'null'
                  required:
                    - street
                    - street2
                    - postalCode
                    - city
                    - region
                    - countryCode
                    - country
                postalAddress:
                  type:
                    - object
                    - 'null'
                  properties:
                    street:
                      type:
                        - string
                        - 'null'
                    street2:
                      type:
                        - string
                        - 'null'
                    postalCode:
                      type:
                        - string
                        - 'null'
                    city:
                      type:
                        - string
                        - 'null'
                    region:
                      type:
                        - string
                        - 'null'
                    countryCode:
                      type:
                        - string
                        - 'null'
                    country:
                      type:
                        - string
                        - 'null'
                  required:
                    - street
                    - street2
                    - postalCode
                    - city
                    - region
                    - countryCode
                    - country
                industryCode:
                  type:
                    - string
                    - 'null'
                industryDescription:
                  type:
                    - string
                    - 'null'
                naceCode:
                  type:
                    - string
                    - 'null'
                numberOfEmployees:
                  type:
                    - integer
                    - 'null'
                website:
                  type:
                    - string
                    - 'null'
                email:
                  type:
                    - string
                    - 'null'
                shareCapital:
                  type:
                    - number
                    - 'null'
                capitalCurrency:
                  type:
                    - string
                    - 'null'
                businessDescription:
                  type:
                    - string
                    - 'null'
                sectorCode:
                  type:
                    - string
                    - 'null'
                sectorDescription:
                  type:
                    - string
                    - 'null'
                isGroupMember:
                  type:
                    - boolean
                    - 'null'
                registrySource:
                  type: string
                fetchedAt:
                  type: string
                sourceUpdatedAt:
                  type: string
                contacts:
                  type: array
                  description: >-
                    rawData and rawResponseMeta are intentionally excluded.

                    contacts included: type+value only (no rawData from
                    sub-DTO).
                  items: {}
                schemaVersion:
                  type: integer
              required:
                - registrationNumber
                - countryCode
                - country
                - vatNumber
                - name
                - tradingName
                - status
                - statusCode
                - legalForm
                - legalFormCode
                - registrationDate
                - incorporationDate
                - dissolutionDate
                - address
                - postalAddress
                - industryCode
                - industryDescription
                - naceCode
                - numberOfEmployees
                - website
                - email
                - shareCapital
                - capitalCurrency
                - businessDescription
                - sectorCode
                - sectorDescription
                - isGroupMember
                - registrySource
                - fetchedAt
                - sourceUpdatedAt
                - contacts
                - schemaVersion
            - type: 'null'
            - type: object
              properties:
                industryCode:
                  type:
                    - string
                    - 'null'
                industryDescription:
                  type:
                    - string
                    - 'null'
              required:
                - industryCode
                - industryDescription
        nationalIdLast4:
          type:
            - string
            - 'null'
          description: >-
            Person fields — always declared; null when client is a company.

            national_id intentionally omitted (full value requires a dedicated
            endpoint + audit log).
        dateOfBirth:
          type:
            - string
            - 'null'
        personSnapshot:
          type:
            - object
            - 'null'
          properties:
            name:
              type: string
            countryCode:
              type: string
            nationalIdLast4:
              type:
                - string
                - 'null'
            dateOfBirth:
              type:
                - string
                - 'null'
            address:
              type:
                - string
                - 'null'
          required:
            - name
            - countryCode
            - nationalIdLast4
            - dateOfBirth
            - address
        status:
          type: string
          description: Status
        onboardedAt:
          type: string
        riskClassification:
          type: string
          description: AML summary (read-only, set by compliance systems)
        cddLevel:
          type: string
        pepStatus:
          type: string
        sanctionsStatus:
          type: string
        amlLastReviewedAt:
          type:
            - string
            - 'null'
        amlNextReviewDueAt:
          type:
            - string
            - 'null'
        conflictCheckStatus:
          type: string
          description: Conflict check
        conflictCheckedAt:
          type:
            - string
            - 'null'
        conflictCheckNotes:
          type: string
        engagementType:
          type: string
          description: Engagement
        taxResidenceCountryCode:
          type: string
          description: Tax / financial
        vatNumber:
          type: string
        lei:
          type: string
        preferredLanguage:
          type: string
          description: Comms
        notes:
          type: string
          description: Freeform
        tags:
          type: string
        lastSyncedAt:
          type:
            - string
            - 'null'
          description: Meta
        createdBy:
          type: string
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
        registryId:
          type:
            - integer
            - 'null'
          description: Entity chain registry ID
      required:
        - id
        - type
        - displayName
        - countryCode
        - registrationNumber
        - companySnapshot
        - nationalIdLast4
        - dateOfBirth
        - personSnapshot
        - status
        - onboardedAt
        - riskClassification
        - cddLevel
        - pepStatus
        - sanctionsStatus
        - amlLastReviewedAt
        - amlNextReviewDueAt
        - conflictCheckStatus
        - conflictCheckedAt
        - conflictCheckNotes
        - engagementType
        - taxResidenceCountryCode
        - vatNumber
        - lei
        - preferredLanguage
        - notes
        - tags
        - lastSyncedAt
        - createdBy
        - createdAt
        - updatedAt
        - registryId
      title: ClientListResource
    ConfigureCredentialsV1Request:
      type: object
      description: >-
        V1 Form Request for PUT
        productmanagement/v1/products/{slug}/activate/credentials.


        Validation only — authorization is handled in the controller via
        EntityPermissions::authorize().

        Accepts camelCase `integrationId` (optional, auto-resolved when only one
        is attached).
      properties:
        credentialType:
          type: string
          maxLength: 100
        integrationId:
          type: string
          maxLength: 36
        credentials:
          type: array
          items:
            type: string
          minItems: 1
      required:
        - credentials
      title: ConfigureCredentialsV1Request
    ConsentDecisionRequest:
      type: object
      description: >-
        The consent decision for `POST oauth/v1/consent/{authorizationId}`.


        `roles` and `capabilities` may each be omitted, but an approval must
        grant

        at least one of the two. Both can only narrow what the authorization

        request asked for — never widen it.


        `delegate` is the user's "act on my behalf" choice for delegated access
        —

        optional, defaults to false, and only accepted when the authorization

        request asked for delegation.


        `sponsored` is the consent-time ownership classification: install for
        the

        organization (false) versus connect for myself on this workspace (true).

        REQUIRED, with no server-side default — the consent screen is a forced

        choice (both options start unselected, Approve stays disabled until one
        is

        picked), so the client always sends an explicit boolean on both
        `approve`

        and `deny` (deny's value is inert but still present).
      properties:
        decision:
          type: string
          enum:
            - approve
            - deny
        delegate:
          type: boolean
          description: |-
            Opt in to delegated access ("act on your behalf"). Only valid
            when the authorization request asked for it.
        sponsored:
          type: boolean
          description: Ownership classification — forced choice, no default (LEX-109).
        roles:
          type: array
          items:
            type: string
        capabilities:
          type: array
          items:
            type: string
      required:
        - decision
        - sponsored
      title: ConsentDecisionRequest
    ConstructIbanV1Request:
      type: object
      description: |-
        Validation for POST bank/v1/iban/construct.

        Requires `bban` and either `country` or `bic`.
      properties:
        bban:
          type: string
        country:
          type: string
          minLength: 2
          maxLength: 2
        bic:
          type: string
          minLength: 8
          maxLength: 11
      required:
        - bban
      title: ConstructIbanV1Request
    CounterpartScanV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/accounts/{accountId}/counterpart-scan.


        Accepts camelCase external names.


        This endpoint does not support the Idempotency-Key header: re-sending

        dispatches a new scan.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        fromDate:
          type: string
          format: date
        dryRun:
          type: boolean
      title: CounterpartScanV1Request
    CountryFromBicV1Request:
      type: object
      description: |-
        Validation for POST bank/v1/bic/country.

        Requires `bic` (8-11 chars).
      properties:
        bic:
          type: string
          minLength: 8
          maxLength: 11
      required:
        - bic
      title: CountryFromBicV1Request
    CreateBulkRefreshJobV1Request:
      type: object
      description: |-
        Validates the body of POST company/v1/jobs/bulk-refresh.
        Authorization enforced by EntityPermissions in the controller.
      properties:
        forceRefresh:
          type: boolean
        companyIds:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 1000
        subsets:
          type: array
          items:
            type: string
      required:
        - companyIds
      title: CreateBulkRefreshJobV1Request
    CreateImportJobV1Request:
      type: object
      description: |-
        Validates the body of POST company/v1/jobs/import.
        Authorization enforced by EntityPermissions in the controller.
      properties:
        profile:
          type: string
        priority:
          type: string
          enum:
            - low
            - normal
            - high
        companyIds:
          type: array
          items:
            type: string
          minItems: 1
        subsets:
          type: array
          items:
            type: string
      required:
        - companyIds
      title: CreateImportJobV1Request
    CreateInvitationRequest:
      type: object
      properties:
        member_type:
          type: string
          maxLength: 50
        member_email:
          type:
            - string
            - 'null'
          format: email
          maxLength: 255
        member_id:
          type:
            - string
            - 'null'
          maxLength: 255
        requested_role_key:
          type: string
          maxLength: 50
        message:
          type:
            - string
            - 'null'
          maxLength: 2000
      required:
        - member_type
        - requested_role_key
      title: CreateInvitationRequest
    CreatePersonalAccessTokenV1Request:
      type: object
      description: >-
        Validates POST users/v1/me/tokens.


        expiresAt is optional — PersonalAccessTokenService defaults it to now+90

        days when omitted. When supplied it must be strictly in the future (no

        past/now expiry) and no further out than now+365 days — both enforced

        here as pure date-range validation; the max-10-active-PATs cap is
        business

        logic and lives in PersonalAccessTokenService::create() instead.


        Validation only — authorization (human-user-only) is enforced in the

        controller via ResolvesRequestActor::userContextRequired().
      properties:
        name:
          type: string
          maxLength: 255
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - name
      title: CreatePersonalAccessTokenV1Request
    DatasetProfileV1Resource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        scope:
          type: string
        profession:
          type:
            - string
            - 'null'
        subProfession:
          type:
            - string
            - 'null'
        subsetSelection:
          type: array
          items: {}
        providerPriorities:
          type: array
          items: {}
        isDefault:
          type: boolean
        usageCount:
          type: integer
      required:
        - id
        - name
        - description
        - scope
        - profession
        - subProfession
        - subsetSelection
        - providerPriorities
        - isDefault
        - usageCount
      title: DatasetProfileV1Resource
    DatasetSubsetTypeV1Resource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        model:
          type: string
      required:
        - id
        - type
        - name
        - description
        - model
      title: DatasetSubsetTypeV1Resource
    DatasetV1Resource:
      type: object
      properties:
        id:
          type: string
        datasetRelationId:
          type:
            - string
            - 'null'
        dataVersion:
          type: string
        providerId:
          type: string
        providerVersion:
          type: string
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
        subsets:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              type:
                type: string
              subsetId:
                type: string
              subsetType:
                type:
                  - object
                  - 'null'
                properties:
                  id:
                    type: string
                  type:
                    type: string
                  name:
                    type: string
                  description:
                    type:
                      - string
                      - 'null'
                required:
                  - id
                  - type
                  - name
                  - description
            required:
              - id
              - type
              - subsetId
              - subsetType
        groups:
          type: string
      required:
        - id
        - datasetRelationId
        - dataVersion
        - providerId
        - providerVersion
        - createdAt
        - updatedAt
      title: DatasetV1Resource
    DiscoverAccountsV1Request:
      type: object
      description: >-
        Validates the body of POST accounttracking/v1/accounts/discover.


        Triggers a Neonomics session discovery flow. The returned session UUID

        is used in subsequent GET sessions/{uuid}/accounts and POST
        sessions/{uuid}/track.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        bankId:
          type: string
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
        accountType:
          type: string
          enum:
            - private
            - company
            - payment
      required:
        - bankId
        - countryCode
        - accountType
      title: DiscoverAccountsV1Request
    EffectivePermissionsV1Resource:
      anyOf:
        - type: object
          properties:
            userId:
              type:
                - string
                - 'null'
            entityType:
              type:
                - string
                - 'null'
            entityId:
              type:
                - string
                - 'null'
            permissions:
              anyOf:
                - type: string
                - type: array
                  items:
                    type: string
                  minItems: 0
                  maxItems: 0
                  additionalItems: false
            count:
              anyOf:
                - type: string
                - type: integer
                  enum:
                    - 0
          required:
            - userId
            - entityType
            - entityId
            - permissions
            - count
        - type: object
          properties:
            userId:
              type:
                - string
                - 'null'
            entityType:
              type:
                - string
                - 'null'
            entityId:
              type:
                - string
                - 'null'
            permissions:
              type: array
              items: {}
            summary:
              type: object
              properties:
                total:
                  anyOf:
                    - type: string
                    - type: integer
                      enum:
                        - 0
                fromRoles:
                  anyOf:
                    - type: string
                    - type: integer
                      enum:
                        - 0
                fromDirectGrants:
                  anyOf:
                    - type: string
                    - type: integer
                      enum:
                        - 0
                fromInheritance:
                  anyOf:
                    - type: string
                    - type: integer
                      enum:
                        - 0
              required:
                - total
                - fromRoles
                - fromDirectGrants
                - fromInheritance
          required:
            - userId
            - entityType
            - entityId
            - permissions
            - summary
      title: EffectivePermissionsV1Resource
    EntityAddressResource:
      type: object
      properties:
        id:
          type: string
        entityType:
          type: string
        entityId:
          type: string
        addressType:
          type: string
        label:
          type:
            - string
            - 'null'
        addressLine1:
          type:
            - string
            - 'null'
        addressLine2:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        stateProvince:
          type:
            - string
            - 'null'
        postalCode:
          type:
            - string
            - 'null'
        countryCode:
          type:
            - string
            - 'null'
        isPrimary:
          type: boolean
        isActive:
          type: boolean
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - entityType
        - entityId
        - addressType
        - label
        - addressLine1
        - addressLine2
        - city
        - stateProvince
        - postalCode
        - countryCode
        - isPrimary
        - isActive
        - createdAt
        - updatedAt
      title: EntityAddressResource
    EntityConnectionResource:
      type: object
      properties:
        id:
          type: string
        app:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
            name:
              type: string
            status:
              type: string
            logoUrl:
              type: string
            homepageUrl:
              type: string
          required:
            - id
            - name
            - status
            - logoUrl
            - homepageUrl
        connector:
          type:
            - object
            - 'null'
          description: |-
            The Connector this connection was established through — NOT
            derivable from app.id/app.name for grouping purposes: every
            connection-born App is named after its connector
            (AppConsentService::grantConsent), so distinct members
            connecting through the SAME connector get distinct app ids but
            IDENTICAL app names. The "Member-connected agents" view groups
            by connector (2026-08-17 UX review), which needs this stable
            id — nullable because connector_id is nullOnDelete.
          properties:
            id:
              type: string
            name:
              type: string
          required:
            - id
            - name
        grantedRoles:
          type: array
          items: {}
        delegated:
          type: boolean
        sponsored:
          type: boolean
          description: |-
            Ownership archetype (LEX-109 / ADR §9) — see OAuthConsentResource's
            `sponsored` field doc comment for the two values' meaning. This
            is what splits the entity's Access Management view into
            "Organization integrations" (false) vs "Member-connected agents"
            (true).
        grantedBy:
          type: object
          properties:
            userId:
              type: string
            name:
              type: string
            email:
              type: string
          required:
            - userId
            - name
            - email
        grantedAt:
          type:
            - string
            - 'null'
        revokedAt:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - active
            - revoked
      required:
        - id
        - app
        - connector
        - grantedRoles
        - delegated
        - sponsored
        - grantedBy
        - grantedAt
        - revokedAt
        - status
      title: EntityConnectionResource
    EntityContactResource:
      type: object
      properties:
        id:
          type: integer
        entityType:
          type: string
        entityId:
          type: string
        contactType:
          type: string
        contactValue:
          type: string
        label:
          type:
            - string
            - 'null'
        isPrimary:
          type: boolean
        isVerified:
          type: boolean
        verifiedAt:
          type:
            - string
            - 'null'
        isActive:
          type: boolean
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - entityType
        - entityId
        - contactType
        - contactValue
        - label
        - isPrimary
        - isVerified
        - verifiedAt
        - isActive
        - createdAt
        - updatedAt
      title: EntityContactResource
    EntityHierarchyV1Resource:
      type: object
      properties:
        root:
          type:
            - string
            - 'null'
        totalEntities:
          anyOf:
            - type: string
            - type: integer
              enum:
                - 0
      required:
        - root
        - totalEntities
      title: EntityHierarchyV1Resource
    EntityMediaResource:
      type: object
      properties:
        id:
          type: integer
        entityType:
          type: string
        entityId:
          type: string
        mediaType:
          type: string
        fileName:
          type: string
        fileSize:
          type:
            - integer
            - 'null'
        mimeType:
          type:
            - string
            - 'null'
        url:
          type: string
        metadata:
          type:
            - array
            - 'null'
          items: {}
        uploadedBy:
          type:
            - integer
            - 'null'
        isActive:
          type: boolean
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - entityType
        - entityId
        - mediaType
        - fileName
        - fileSize
        - mimeType
        - url
        - metadata
        - uploadedBy
        - isActive
        - createdAt
        - updatedAt
      title: EntityMediaResource
    EntityRelationship:
      type: object
      properties:
        id:
          type: string
        parent_entity_id:
          type: string
        parent_entity_type:
          type: string
        child_entity_id:
          type: string
        child_entity_type:
          type: string
        relationship_type:
          type: string
        established_at:
          type: string
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        established_by:
          type:
            - integer
            - 'null'
        is_active:
          type: boolean
        status:
          type: string
        invitation_token:
          type:
            - string
            - 'null'
        invitation_token_expires_at:
          type:
            - string
            - 'null'
          format: date-time
        invited_at:
          type:
            - string
            - 'null'
          format: date-time
        accepted_at:
          type:
            - string
            - 'null'
          format: date-time
        rejected_at:
          type:
            - string
            - 'null'
          format: date-time
        suspended_at:
          type:
            - string
            - 'null'
          format: date-time
        invited_by:
          type:
            - integer
            - 'null'
        invitation_message:
          type:
            - string
            - 'null'
        requested_role_key:
          type:
            - string
            - 'null'
        cascade_mode:
          type: string
        tenant_id:
          type:
            - integer
            - 'null'
        metadata:
          type:
            - array
            - 'null'
          items: {}
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - parent_entity_id
        - parent_entity_type
        - child_entity_id
        - child_entity_type
        - relationship_type
        - established_at
        - expires_at
        - established_by
        - is_active
        - status
        - invitation_token
        - invitation_token_expires_at
        - invited_at
        - accepted_at
        - rejected_at
        - suspended_at
        - invited_by
        - invitation_message
        - requested_role_key
        - cascade_mode
        - tenant_id
        - metadata
        - created_at
        - updated_at
        - deleted_at
      title: EntityRelationship
    FetchDetailedV1Request:
      type: object
      description: |-
        Validates the body of POST company/v1/companies/{id} (detailed fetch).
        Authorization enforced by EntityPermissions in the controller.
      properties:
        profile:
          type: string
        priorities:
          type: array
          items:
            type: string
        subsets:
          type: array
          items:
            type: string
            enum:
              - information
              - addresses
              - financials
              - metric_snapshots
              - rating
              - announcements
              - events
              - roles
              - signatories
              - shareholders
              - exceptions
              - activity_classifications
              - group_structure
        options:
          type: object
          properties:
            maxAge:
              type: string
            forceRefresh:
              type: boolean
            createAccessGrants:
              type: boolean
      title: FetchDetailedV1Request
    ForgotPasswordV1Request:
      type: object
      description: >-
        Validation for POST auth/v1/forgot-password.


        Mirrors Manda\Authentication\Http\Requests\ForgotPasswordRequest
        exactly.

        Rate-limiting is handled in PasswordResetV1Controller.
      properties:
        email:
          type: string
          format: email
          maxLength: 255
        entity_type:
          type: string
          maxLength: 50
        recaptcha_token:
          type: string
      required:
        - email
      title: ForgotPasswordV1Request
    GrantMemberPermissionRequest:
      type: object
      description: |-
        Validates grant-permission payload for group members.
        Authorization enforced by route middleware (entity.role:group,admin).
      properties:
        permission:
          type: string
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - permission
      title: GrantMemberPermissionRequest
    GrantPermissionV1Request:
      type: object
      properties:
        permission:
          type: string
        options:
          type: object
          properties:
            expires_at:
              type:
                - string
                - 'null'
              format: date-time
            metadata:
              type:
                - array
                - 'null'
              items:
                type: string
            tenant_id:
              type:
                - integer
                - 'null'
      required:
        - permission
      title: GrantPermissionV1Request
    GrantProjectPermissionRequest:
      type: object
      description: |-
        Validates grant-permission payload for project users.
        Authorization enforced by route middleware (entity.role:project,admin).
      properties:
        permission:
          type: string
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - permission
      title: GrantProjectPermissionRequest
    GroupResource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        description:
          type:
            - string
            - 'null'
        groupType:
          type: string
        metadata:
          type:
            - array
            - 'null'
          items: {}
        isActive:
          type: boolean
        createdBy:
          type: integer
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - name
        - slug
        - description
        - groupType
        - metadata
        - isActive
        - createdBy
        - createdAt
        - updatedAt
      title: GroupResource
    HasRoleV1Request:
      type: object
      properties:
        user_id:
          type: integer
          minimum: 1
        entity_type:
          type: string
          enum:
            - user
            - tenant
            - group
            - project
            - client
            - case
            - consent
        entity_id:
          type: integer
          minimum: 1
        role_key:
          type: string
      required:
        - user_id
        - entity_type
        - entity_id
        - role_key
      title: HasRoleV1Request
    HasRoleV1Resource:
      type: object
      properties:
        hasRole:
          anyOf:
            - type: string
            - type: boolean
        userId:
          type:
            - string
            - 'null'
        entityType:
          type:
            - string
            - 'null'
        entityId:
          type:
            - string
            - 'null'
        roleKey:
          type:
            - string
            - 'null'
      required:
        - hasRole
        - userId
        - entityType
        - entityId
        - roleKey
      title: HasRoleV1Resource
    IdentifyBankV1Request:
      type: object
      description: |-
        Validation for POST bank/v1/identify, POST bank/v1/identify/bank,
        and POST bank/v1/identify/bic.

        Requires either `iban` or `bban` (with `country`).
      properties:
        iban:
          type: string
        bban:
          type: string
        country:
          type: string
          minLength: 2
          maxLength: 2
      title: IdentifyBankV1Request
    ImportCompanyV1Request:
      type: object
      description: |-
        Validates the body of POST company/v1/companies/{id}/import.
        Authorization enforced by EntityPermissions in the controller.
      properties:
        source:
          type: string
        profile:
          type: string
        createAccessGrants:
          type: boolean
        subsets:
          type: array
          items:
            type: string
      title: ImportCompanyV1Request
    InitiateRedirectV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/consents/{consent}/initiate-redirect.


        Returns JSON { data: { consentId, redirectUrl, expiresIn }, meta: {
        requestId } }.

        This is a JSON endpoint — the client receives the URL and navigates to
        it

        itself (no HTTP 302 is issued from the server).


        This endpoint does not support the Idempotency-Key header.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        bankId:
          type: string
          maxLength: 50
        redirectUrl:
          type: string
          format: uri
          maxLength: 255
      required:
        - bankId
      title: InitiateRedirectV1Request
    InvitationResource:
      type: object
      properties:
        id:
          type: string
        parentEntityType:
          type: string
        parentEntityId:
          type: string
        childEntityType:
          type: string
        childEntityId:
          type: string
        relationshipType:
          type: string
        status:
          type: string
        invitationToken:
          type: string
        invitationTokenExpiresAt:
          type:
            - string
            - 'null'
        invitedAt:
          type:
            - string
            - 'null'
        acceptedAt:
          type:
            - string
            - 'null'
        rejectedAt:
          type:
            - string
            - 'null'
        suspendedAt:
          type:
            - string
            - 'null'
        invitedBy:
          type: string
        invitationMessage:
          type: string
        requestedRoleKey:
          type: string
        establishedBy:
          type: string
        establishedAt:
          type:
            - string
            - 'null'
        expiresAt:
          type:
            - string
            - 'null'
        metadata:
          type: string
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - parentEntityType
        - parentEntityId
        - childEntityType
        - childEntityId
        - relationshipType
        - status
        - invitationToken
        - invitationTokenExpiresAt
        - invitedAt
        - acceptedAt
        - rejectedAt
        - suspendedAt
        - invitedBy
        - invitationMessage
        - requestedRoleKey
        - establishedBy
        - establishedAt
        - expiresAt
        - metadata
        - createdAt
        - updatedAt
      title: InvitationResource
    LegalCaseListResource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: Identity
        caseIdDisplay:
          type: string
        caseType:
          type: string
        status:
          type: string
          description: Status
        clientId:
          type: string
          description: Client link
        client:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            displayName:
              type: string
            countryCode:
              type: string
            registrationNumber:
              type:
                - string
                - 'null'
              description: Company fields — always declared; null when client is a person
            companySnapshot:
              anyOf:
                - type: object
                  properties:
                    registrationNumber:
                      type: string
                    countryCode:
                      type: string
                    country:
                      type:
                        - string
                        - 'null'
                    vatNumber:
                      type:
                        - string
                        - 'null'
                    name:
                      type: string
                    tradingName:
                      type:
                        - string
                        - 'null'
                    status:
                      type: string
                    statusCode:
                      type:
                        - string
                        - 'null'
                    legalForm:
                      type:
                        - string
                        - 'null'
                    legalFormCode:
                      type:
                        - string
                        - 'null'
                    registrationDate:
                      type: string
                    incorporationDate:
                      type: string
                    dissolutionDate:
                      type: string
                    address:
                      type:
                        - object
                        - 'null'
                      properties:
                        street:
                          type:
                            - string
                            - 'null'
                        street2:
                          type:
                            - string
                            - 'null'
                        postalCode:
                          type:
                            - string
                            - 'null'
                        city:
                          type:
                            - string
                            - 'null'
                        region:
                          type:
                            - string
                            - 'null'
                        countryCode:
                          type:
                            - string
                            - 'null'
                        country:
                          type:
                            - string
                            - 'null'
                      required:
                        - street
                        - street2
                        - postalCode
                        - city
                        - region
                        - countryCode
                        - country
                    postalAddress:
                      type:
                        - object
                        - 'null'
                      properties:
                        street:
                          type:
                            - string
                            - 'null'
                        street2:
                          type:
                            - string
                            - 'null'
                        postalCode:
                          type:
                            - string
                            - 'null'
                        city:
                          type:
                            - string
                            - 'null'
                        region:
                          type:
                            - string
                            - 'null'
                        countryCode:
                          type:
                            - string
                            - 'null'
                        country:
                          type:
                            - string
                            - 'null'
                      required:
                        - street
                        - street2
                        - postalCode
                        - city
                        - region
                        - countryCode
                        - country
                    industryCode:
                      type:
                        - string
                        - 'null'
                    industryDescription:
                      type:
                        - string
                        - 'null'
                    naceCode:
                      type:
                        - string
                        - 'null'
                    numberOfEmployees:
                      type:
                        - integer
                        - 'null'
                    website:
                      type:
                        - string
                        - 'null'
                    email:
                      type:
                        - string
                        - 'null'
                    shareCapital:
                      type:
                        - number
                        - 'null'
                    capitalCurrency:
                      type:
                        - string
                        - 'null'
                    businessDescription:
                      type:
                        - string
                        - 'null'
                    sectorCode:
                      type:
                        - string
                        - 'null'
                    sectorDescription:
                      type:
                        - string
                        - 'null'
                    isGroupMember:
                      type:
                        - boolean
                        - 'null'
                    registrySource:
                      type: string
                    fetchedAt:
                      type: string
                    sourceUpdatedAt:
                      type: string
                    contacts:
                      type: array
                      description: >-
                        rawData and rawResponseMeta are intentionally excluded.

                        contacts included: type+value only (no rawData from
                        sub-DTO).
                      items: {}
                    schemaVersion:
                      type: integer
                  required:
                    - registrationNumber
                    - countryCode
                    - country
                    - vatNumber
                    - name
                    - tradingName
                    - status
                    - statusCode
                    - legalForm
                    - legalFormCode
                    - registrationDate
                    - incorporationDate
                    - dissolutionDate
                    - address
                    - postalAddress
                    - industryCode
                    - industryDescription
                    - naceCode
                    - numberOfEmployees
                    - website
                    - email
                    - shareCapital
                    - capitalCurrency
                    - businessDescription
                    - sectorCode
                    - sectorDescription
                    - isGroupMember
                    - registrySource
                    - fetchedAt
                    - sourceUpdatedAt
                    - contacts
                    - schemaVersion
                - type: 'null'
                - type: object
                  properties:
                    industryCode:
                      type:
                        - string
                        - 'null'
                    industryDescription:
                      type:
                        - string
                        - 'null'
                  required:
                    - industryCode
                    - industryDescription
            nationalIdLast4:
              type:
                - string
                - 'null'
              description: >-
                Person fields — always declared; null when client is a company.

                national_id intentionally omitted (full value requires a
                dedicated endpoint + audit log).
            dateOfBirth:
              type:
                - string
                - 'null'
            personSnapshot:
              type:
                - object
                - 'null'
              properties:
                name:
                  type: string
                countryCode:
                  type: string
                nationalIdLast4:
                  type:
                    - string
                    - 'null'
                dateOfBirth:
                  type:
                    - string
                    - 'null'
                address:
                  type:
                    - string
                    - 'null'
              required:
                - name
                - countryCode
                - nationalIdLast4
                - dateOfBirth
                - address
            status:
              type: string
              description: Status
            onboardedAt:
              type: string
            riskClassification:
              type:
                - string
                - 'null'
              description: AML summary (read-only, set by compliance systems)
            cddLevel:
              type:
                - string
                - 'null'
            pepStatus:
              type: string
            sanctionsStatus:
              type: string
            amlLastReviewedAt:
              type:
                - string
                - 'null'
            amlNextReviewDueAt:
              type:
                - string
                - 'null'
            conflictCheckStatus:
              type: string
              description: Conflict check
            conflictCheckedAt:
              type:
                - string
                - 'null'
            conflictCheckNotes:
              type:
                - string
                - 'null'
            engagementType:
              type:
                - string
                - 'null'
              description: Engagement
            taxResidenceCountryCode:
              type:
                - string
                - 'null'
              description: Tax / financial
            vatNumber:
              type:
                - string
                - 'null'
            lei:
              type:
                - string
                - 'null'
            preferredLanguage:
              type:
                - string
                - 'null'
              description: Comms
            notes:
              type:
                - string
                - 'null'
              description: Freeform
            tags:
              type:
                - array
                - 'null'
              items: {}
            lastSyncedAt:
              type:
                - string
                - 'null'
              description: Meta
            createdBy:
              type:
                - string
                - 'null'
            createdAt:
              type:
                - string
                - 'null'
            updatedAt:
              type:
                - string
                - 'null'
            registryId:
              type:
                - integer
                - 'null'
              description: Entity chain registry ID
          required:
            - id
            - type
            - displayName
            - countryCode
            - registrationNumber
            - companySnapshot
            - nationalIdLast4
            - dateOfBirth
            - personSnapshot
            - status
            - onboardedAt
            - riskClassification
            - cddLevel
            - pepStatus
            - sanctionsStatus
            - amlLastReviewedAt
            - amlNextReviewDueAt
            - conflictCheckStatus
            - conflictCheckedAt
            - conflictCheckNotes
            - engagementType
            - taxResidenceCountryCode
            - vatNumber
            - lei
            - preferredLanguage
            - notes
            - tags
            - lastSyncedAt
            - createdBy
            - createdAt
            - updatedAt
            - registryId
        openedAt:
          type: string
          description: Dates
        closedAt:
          type: string
        targetCompletionDate:
          type: string
        description:
          type: string
          description: Freeform
        notes:
          type: string
        tags:
          type: string
        team:
          type:
            - object
            - 'null'
          description: >-
            Team — resolved from entity_role_assignments (suppressed on list
            context)
          properties:
            leadAttorney:
              type: string
            caseManager:
              type: string
            stakeholders:
              type: array
              items:
                type: string
          required:
            - leadAttorney
            - caseManager
            - stakeholders
        createdBy:
          type: string
          description: Audit / meta
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
        registryId:
          type:
            - integer
            - 'null'
          description: Entity chain anchor
      required:
        - id
        - name
        - caseIdDisplay
        - caseType
        - status
        - clientId
        - openedAt
        - closedAt
        - targetCompletionDate
        - description
        - notes
        - tags
        - team
        - createdBy
        - createdAt
        - updatedAt
        - registryId
      title: LegalCaseListResource
    LoginV1Request:
      type: object
      description: |-
        Validation for POST auth/v1/login.

        Mirrors Manda\Authentication\Http\Requests\LoginRequest exactly.
        Authorization (rate-limiting, lockout) is handled in AuthV1Controller.
      properties:
        email:
          type: string
          format: email
          maxLength: 255
        password:
          type: string
          minLength: 1
        entity_type:
          type: string
          maxLength: 50
        device_name:
          type: string
          maxLength: 255
        recaptcha_token:
          type: string
        context:
          type: string
          enum:
            - portal
            - admin
      required:
        - email
        - password
      title: LoginV1Request
    MeEntityPermissionsV1Resource:
      type: object
      properties:
        scope:
          type:
            - string
            - 'null'
        entityPermissions:
          type: string
      required:
        - scope
        - entityPermissions
      title: MeEntityPermissionsV1Resource
    MePermissionsV1Resource:
      type: object
      properties:
        scope:
          type:
            - string
            - 'null'
        items:
          anyOf:
            - type: string
            - type: array
              items:
                type: string
              minItems: 0
              maxItems: 0
              additionalItems: false
      required:
        - scope
        - items
      title: MePermissionsV1Resource
    MessageBag:
      type: array
      items: {}
      title: MessageBag
    NewAccessToken:
      type: object
      additionalProperties:
        type: string
      title: NewAccessToken
    OAuthConsentResource:
      type: object
      properties:
        id:
          type: string
        app:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            logoUrl:
              type: string
              description: The app's branding, from its connector.
            homepageUrl:
              type: string
          required:
            - id
            - name
            - logoUrl
            - homepageUrl
        grantedRoles:
          type: array
          items: {}
        delegated:
          type: boolean
          description: |-
            Whether this app also holds delegated access from you
            ("acts on your behalf") in the granted entity's scope.
        sponsored:
          type: boolean
          description: |-
            Ownership archetype (LEX-109 / ADR §9): true = a personal
            "deputy" you connected for yourself (principal-managed, dies
            with your own access here); false = an organization
            installation (LEX-94 semantics, unchanged).
        entity:
          type: object
          properties:
            type:
              type: string
            id:
              type: string
            name:
              type:
                - string
                - 'null'
          required:
            - type
            - id
            - name
        grantedAt:
          type:
            - string
            - 'null'
        revokedAt:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - active
            - revoked
      required:
        - id
        - app
        - grantedRoles
        - delegated
        - sponsored
        - entity
        - grantedAt
        - revokedAt
        - status
      title: OAuthConsentResource
    PackageProductV1Resource:
      type: object
      properties:
        productId:
          type: string
        grantedTier:
          type: string
        autoActivate:
          type: boolean
        includedFeatures:
          type:
            - array
            - 'null'
          items: {}
        limits:
          type:
            - array
            - 'null'
          items: {}
        product:
          $ref: '#/components/schemas/ProductV1Resource'
      required:
        - productId
        - grantedTier
        - autoActivate
        - includedFeatures
        - limits
      title: PackageProductV1Resource
    PackageV1Resource:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        icon:
          type:
            - string
            - 'null'
        packageType:
          type: string
        tierLevel:
          type:
            - integer
            - 'null'
        tierGroup:
          type: string
        isPublic:
          type: boolean
        audience:
          type:
            - array
            - 'null'
          items: {}
        status:
          type: string
        sortOrder:
          type: integer
        priceAmount:
          type:
            - string
            - 'null'
        priceCurrency:
          type:
            - string
            - 'null'
        billingPeriod:
          type:
            - string
            - 'null'
        metadata:
          type:
            - array
            - 'null'
          items: {}
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
        products:
          type: array
          items:
            $ref: '#/components/schemas/PackageProductV1Resource'
        isEntitySubscribed:
          type: boolean
          description: Set by the controller when entity scope is available
      required:
        - id
        - slug
        - name
        - description
        - icon
        - packageType
        - tierLevel
        - tierGroup
        - isPublic
        - audience
        - status
        - sortOrder
        - priceAmount
        - priceCurrency
        - billingPeriod
        - metadata
        - createdAt
        - updatedAt
      title: PackageV1Resource
    ParseIbanV1Request:
      type: object
      description: |-
        Validation for POST bank/v1/iban/parse.

        Requires `iban`.
      properties:
        iban:
          type: string
      required:
        - iban
      title: ParseIbanV1Request
    PermissionCheckBatchV1Resource:
      type: object
      properties:
        userId:
          type:
            - string
            - 'null'
        entityType:
          type:
            - string
            - 'null'
        entityId:
          type:
            - string
            - 'null'
        permissions:
          anyOf:
            - type: string
            - type: array
              items:
                type: string
              minItems: 0
              maxItems: 0
              additionalItems: false
        checkedAt:
          type: string
      required:
        - userId
        - entityType
        - entityId
        - permissions
        - checkedAt
      title: PermissionCheckBatchV1Resource
    PermissionCheckV1Resource:
      type: object
      properties:
        hasPermission:
          anyOf:
            - type: string
            - type: boolean
        userId:
          type:
            - string
            - 'null'
        entityType:
          type:
            - string
            - 'null'
        entityId:
          type:
            - string
            - 'null'
        permission:
          type:
            - string
            - 'null'
        checkedAt:
          type: string
      required:
        - hasPermission
        - userId
        - entityType
        - entityId
        - permission
        - checkedAt
      title: PermissionCheckV1Resource
    PermissionDefinitionsV1Resource:
      type: array
      items: {}
      title: PermissionDefinitionsV1Resource
    PermissionGrantV1Resource:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
        userId:
          type:
            - string
            - 'null'
        entityType:
          type:
            - string
            - 'null'
        entityId:
          type:
            - string
            - 'null'
        permission:
          type:
            - string
            - 'null'
        grantedBy:
          type:
            - string
            - 'null'
        grantedAt:
          type:
            - string
            - 'null'
        expiresAt:
          type:
            - string
            - 'null'
        isActive:
          type: boolean
      required:
        - id
        - userId
        - entityType
        - entityId
        - permission
        - grantedBy
        - grantedAt
        - expiresAt
        - isActive
      title: PermissionGrantV1Resource
    ProductActivationV1Resource:
      type: object
      properties:
        id:
          type: string
        entityType:
          type: string
        entityId:
          type: string
        productId:
          type: string
        status:
          type: string
        activatedBy:
          type:
            - string
            - 'null'
        activatedAt:
          type:
            - string
            - 'null'
        deactivatedAt:
          type:
            - string
            - 'null'
        activationContext:
          type:
            - array
            - 'null'
          items: {}
        metadata:
          type:
            - array
            - 'null'
          items: {}
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
        product:
          $ref: '#/components/schemas/ProductV1Resource'
        integrations:
          type: array
          description: >-
            Every integration backing this activation, with pivot status +
            attachment timestamp.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              slug:
                type: string
              status:
                type:
                  - string
                  - 'null'
              health:
                type: string
              supportedCountries:
                type:
                  - array
                  - 'null'
                items: {}
              pivotStatus:
                type: string
              attachedAt:
                type:
                  - string
                  - 'null'
            required:
              - id
              - name
              - slug
              - status
              - health
              - supportedCountries
              - pivotStatus
              - attachedAt
      required:
        - id
        - entityType
        - entityId
        - productId
        - status
        - activatedBy
        - activatedAt
        - deactivatedAt
        - activationContext
        - metadata
        - createdAt
        - updatedAt
      title: ProductActivationV1Resource
    ProductEligibilityV1Resource:
      type: object
      properties:
        eligible:
          type: string
        alreadyActivated:
          type: string
        existingActivationStatus:
          type: string
        reason:
          type: string
        resumable:
          type: string
        existingActivationId:
          type: string
        integrationsAvailable:
          type: string
        availableIntegrationCount:
          type: string
        currentPackageSlug:
          type: string
        currentPackageName:
          type: string
        currentTierLevel:
          type: string
        requiredPackageSlug:
          type: string
        requiredPackageName:
          type: string
        requiredTierLevel:
          type: string
        tierMet:
          type: string
        featureAvailability:
          type:
            - string
            - 'null'
      required:
        - eligible
        - alreadyActivated
        - existingActivationStatus
        - reason
        - resumable
        - existingActivationId
        - integrationsAvailable
        - availableIntegrationCount
        - currentPackageSlug
        - currentPackageName
        - currentTierLevel
        - requiredPackageSlug
        - requiredPackageName
        - requiredTierLevel
        - tierMet
        - featureAvailability
      title: ProductEligibilityV1Resource
    ProductFeatureV1Resource:
      type: object
      properties:
        id:
          type: string
        featureKey:
          type: string
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        isRequired:
          type: boolean
        sortOrder:
          type: integer
      required:
        - id
        - featureKey
        - name
        - description
        - isRequired
        - sortOrder
      title: ProductFeatureV1Resource
    ProductV1Resource:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        icon:
          type:
            - string
            - 'null'
        category:
          type:
            - string
            - 'null'
        productType:
          type: string
        status:
          type: string
        isFree:
          type: boolean
        requiresIntegration:
          type: boolean
        sortOrder:
          type: integer
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
        features:
          type: array
          items:
            $ref: '#/components/schemas/ProductFeatureV1Resource'
        defaultIntegrationSlugs:
          type: array
          items: {}
        metadata:
          type:
            - array
            - 'null'
          items: {}
      required:
        - id
        - slug
        - name
        - description
        - icon
        - category
        - productType
        - status
        - isFree
        - requiresIntegration
        - sortOrder
        - createdAt
        - updatedAt
        - defaultIntegrationSlugs
        - metadata
      title: ProductV1Resource
    ProjectResource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        description:
          type:
            - string
            - 'null'
        projectCode:
          type:
            - string
            - 'null'
        projectType:
          type: string
        status:
          type: string
        priority:
          type: string
        startDate:
          type: string
        endDate:
          type: string
        deadlineDate:
          type: string
        budget:
          type:
            - string
            - 'null'
        currencyCode:
          type: string
        metadata:
          type:
            - array
            - 'null'
          items: {}
        isActive:
          type: boolean
        archivedAt:
          type:
            - string
            - 'null'
        createdBy:
          type: integer
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - name
        - slug
        - description
        - projectCode
        - projectType
        - status
        - priority
        - startDate
        - endDate
        - deadlineDate
        - budget
        - currencyCode
        - metadata
        - isActive
        - archivedAt
        - createdBy
        - createdAt
        - updatedAt
      title: ProjectResource
    PurgeAccountV1Request:
      type: object
      description: >-
        Validates the body of POST accounttracking/v1/accounts/{id}/purge.


        The 'confirm' field must echo the exact account name — that equality
        check

        lives in the controller (it needs the loaded account). This request only

        validates that the fields are present and well-formed.


        The `nuke_everything` mode requires super-admin; authorization is
        enforced

        by EntityPermissions in the controller.


        Accepts camelCase external names; controller maps to snake_case
        internally.
      properties:
        confirm:
          type: string
        mode:
          type: string
          enum:
            - nuke_everything
            - smart_untrack_unless_last
        deleteOrphanedCounterparts:
          type: boolean
      required:
        - confirm
        - mode
      title: PurgeAccountV1Request
    RefetchCompanyV1Request:
      type: object
      description: |-
        Validates the body of POST company/v1/companies/{id}/refetch.
        Authorization enforced by EntityPermissions in the controller.
      properties:
        profile:
          type: string
        priorities:
          type: array
          items:
            type: string
        subsets:
          type: array
          items:
            type: string
      title: RefetchCompanyV1Request
    RegisterV1Request:
      type: object
      description: >-
        Validation for POST auth/v1/register.


        Password complexity rules are read from authentication config at
        runtime.

        Authorization is always true — rate-limiting is handled in
        RegistrationV1Controller.
      properties:
        email:
          type: string
          format: email
          maxLength: 255
        password:
          type: string
          pattern: '[0-9]'
          minLength: 8
        name:
          type: string
          maxLength: 255
        entity_type:
          type: string
          maxLength: 50
        recaptcha_token:
          type: string
        password_confirmation:
          type: string
          pattern: '[0-9]'
          minLength: 8
      required:
        - email
        - password
        - password_confirmation
      title: RegisterV1Request
    ResendVerificationV1Request:
      type: object
      description: >-
        Validation for POST auth/v1/resend-verification.


        Mirrors Manda\Authentication\Http\Requests\ResendVerificationRequest
        exactly.

        Rate-limiting is handled in RegistrationV1Controller.
      properties:
        email:
          type: string
          format: email
          maxLength: 255
        entity_type:
          type: string
          maxLength: 50
      required:
        - email
      title: ResendVerificationV1Request
    ResetPasswordV1Request:
      type: object
      description: |-
        Validation for POST auth/v1/reset-password.

        Mirrors Manda\Authentication\Http\Requests\ResetPasswordRequest exactly.
        Rate-limiting is handled in PasswordResetV1Controller.
      properties:
        token:
          type: string
          format: uuid
        password:
          type: string
          minLength: 8
        password_confirmation:
          type: string
          minLength: 8
      required:
        - token
        - password
        - password_confirmation
      title: ResetPasswordV1Request
    RoleAssignmentV1Resource:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
        userId:
          type:
            - string
            - 'null'
        entityType:
          type:
            - string
            - 'null'
        entityId:
          type:
            - string
            - 'null'
        roleKey:
          type:
            - string
            - 'null'
        roleType:
          type:
            - string
            - 'null'
        assignedBy:
          type:
            - string
            - 'null'
        assignedAt:
          type:
            - string
            - 'null'
        expiresAt:
          type:
            - string
            - 'null'
        isActive:
          type: boolean
      required:
        - id
        - userId
        - entityType
        - entityId
        - roleKey
        - roleType
        - assignedBy
        - assignedAt
        - expiresAt
        - isActive
      title: RoleAssignmentV1Resource
    RoleCatalogV1Resource:
      type: object
      properties:
        key:
          type:
            - string
            - 'null'
        id:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        type:
          anyOf:
            - type: string
            - type: string
              enum:
                - standard
        capabilities:
          anyOf:
            - type: string
            - type: array
              items:
                type: string
              minItems: 0
              maxItems: 0
              additionalItems: false
        hierarchyLevel:
          anyOf:
            - type: string
            - type: integer
              enum:
                - 0
        isBarrier:
          anyOf:
            - type: string
            - type: boolean
        canCascade:
          anyOf:
            - type: string
            - type: boolean
      required:
        - key
        - id
        - name
        - description
        - type
        - capabilities
        - hierarchyLevel
        - isBarrier
        - canCascade
      title: RoleCatalogV1Resource
    ScoringResource:
      type: object
      properties:
        id:
          type: integer
        companyNumber:
          type: string
        companyName:
          type: string
        approved:
          type: boolean
        grossAmount:
          type: string
        currency:
          type: string
        tenantId:
          type: string
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - companyNumber
        - companyName
        - approved
        - grossAmount
        - currency
        - tenantId
        - createdAt
        - updatedAt
      title: ScoringResource
    SelectIntegrationsV1Request:
      type: object
      description: >-
        V1 Form Request for PUT
        productmanagement/v1/products/{slug}/activate/integrations.


        Validation only — authorization is handled in the controller via
        EntityPermissions::authorize().

        Accepts camelCase `integrationIds` (required) and optional `regions`.
      properties:
        integrationIds:
          type: array
          items:
            type: string
            maxLength: 36
          minItems: 1
        regions:
          type: array
          items:
            type: string
            maxLength: 8
      required:
        - integrationIds
      title: SelectIntegrationsV1Request
    SetAliasV1Request:
      type: object
      description: >-
        Validates the body of PUT
        accounttracking/v1/counterparts/{counterpart}/alias.


        Sets a user-specific display alias for the counterpart (stored in

        user_counterpart_aliases, not on the counterpart entity itself).


        Authorization enforced by EntityPermissions in the controller.
      properties:
        alias:
          type: string
          maxLength: 255
      required:
        - alias
      title: SetAliasV1Request
    SetDisplayNameV1Request:
      type: object
      description: >-
        Validates the body of PUT
        accounttracking/v1/counterparts/{counterpart}/display-name.


        Sets the counterpart's display_name column (shared across all users,
        unlike aliases).


        Authorization enforced by EntityPermissions in the controller.
      properties:
        displayName:
          type: string
          maxLength: 255
      required:
        - displayName
      title: SetDisplayNameV1Request
    SetPasswordV1Request:
      type: object
      description: |-
        Validation for POST auth/v1/password.

        Mirrors Manda\Authentication\Http\Requests\SetPasswordRequest exactly.
        Auth:sanctum gate is applied at the route level.
      properties:
        current_password:
          type:
            - string
            - 'null'
        new_password:
          type: string
          minLength: 8
        new_password_confirmation:
          type: string
          minLength: 8
      required:
        - new_password
        - new_password_confirmation
      title: SetPasswordV1Request
    ShareConsentV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/consents/{consent}/visibility.


        Shares the consent with the specified entity scope. The controller
        delegates

        to ConsentManager::shareConsent() / visibility assignment logic.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        scopeType:
          type: string
          enum:
            - user
            - tenant
            - group
            - project
        scopeId:
          type: string
          maxLength: 255
        visibilityLevel:
          type: string
          enum:
            - full
            - limited
            - metadata_only
        expiresAt:
          type: string
          format: date-time
      required:
        - scopeType
        - scopeId
      title: ShareConsentV1Request
    StoreAppClientCredentialRequest:
      type: object
      description: |-
        Validates the payload for issuing (or rotating) an App's OAuth2
        client-credentials set.

        Authorization is enforced by the `entity.permission:app,apps.manage`
        route middleware. This class is validation-only.
      properties:
        name:
          type: string
          maxLength: 255
      title: StoreAppClientCredentialRequest
    StoreAppKeyRequest:
      type: object
      description: |-
        Validates the payload for issuing a new API key for an App.

        Authorization is enforced by the `entity.permission:app,apps.manage`
        route middleware. This class is validation-only.
      properties:
        name:
          type: string
          maxLength: 255
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
      title: StoreAppKeyRequest
    StoreAppRequest:
      type: object
      description: >-
        Validates the payload for creating a new App (machine actor).


        Authorization stays in the controller via
        EntityPermissions::can('apps.create').

        This class is validation-only, mirroring StoreClientRequest.
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        createKey:
          type: boolean
        keyName:
          type: string
          maxLength: 255
        roles:
          type: array
          items:
            type: string
      required:
        - name
      title: StoreAppRequest
    StoreAppRoleRequest:
      type: object
      description: |-
        Validates the payload for granting an App a role on a target entity.

        Authorization is enforced by the `entity.permission:app,apps.manage`
        route middleware; the app-grant subset ceiling is enforced inside
        AppService::assignRole(). This class is validation-only.
      properties:
        entityType:
          type: string
        entityId:
          type: string
        roleKey:
          type: string
      required:
        - entityType
        - entityId
        - roleKey
      title: StoreAppRoleRequest
    StoreCaseRequest:
      type: object
      description: >-
        Validates the payload for creating a new LegalCase.


        External field names follow the camelCase contract (e.g. clientId,
        caseType).

        The controller maps validated camelCase keys to internal snake_case
        column names

        before persisting via toColumns().


        Team assignments are processed after case creation. This request
        validates

        the optional team array so the controller can assign roles atomically.


        External party invitations (external_admin, external_editor,
        external_viewer)

        are NOT processed in this slice. If an external_parties key is present
        it is

        silently ignored — toColumns() strips it.

        TODO: external parties invite — see future Linear ticket for invite
        slice.


        Authorization stays in the controller via
        EntityPermissions::can('cases.create').

        This class is validation-only.
      properties:
        name:
          type: string
          description: Required fields
          maxLength: 255
        clientId:
          type: string
          format: uuid
        caseType:
          type: string
          enum:
            - m_a
            - bankruptcy
            - litigation
            - compliance
            - due_diligence
            - other
        caseIdDisplay:
          type:
            - string
            - 'null'
          description: Optional fields
          maxLength: 50
        status:
          type:
            - string
            - 'null'
          enum:
            - draft
            - open
            - on_hold
            - closed
            - archived
        openedAt:
          type:
            - string
            - 'null'
          format: date-time
        targetCompletionDate:
          type:
            - string
            - 'null'
          format: date-time
        description:
          type:
            - string
            - 'null'
        notes:
          type:
            - string
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
            maxLength: 50
        team:
          type: object
          description: |-
            Internal team assignments (processed post-creation).
            User IDs are integers today; the codebase plans to migrate to UUIDs.
            Validation accepts either by deferring to the exists:users,id check.
          properties:
            leadAttorneyId:
              type:
                - integer
                - 'null'
            caseManagerId:
              type:
                - integer
                - 'null'
            stakeholderIds:
              type:
                - array
                - 'null'
              items:
                type: integer
      required:
        - name
        - clientId
        - caseType
      title: StoreCaseRequest
    StoreClientRequest:
      type: object
      description: >-
        Validates the payload for creating a new Client.


        External field names follow the camelCase contract (e.g. displayName,
        countryCode).

        The controller maps validated camelCase keys to internal snake_case
        column names

        before persisting.


        Authorization stays in the controller via
        EntityPermissions::can('clients.create').

        This class is validation-only.
      properties:
        type:
          type: string
          enum:
            - company
            - person
        displayName:
          type: string
          maxLength: 255
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
        registrationNumber:
          type:
            - string
            - 'null'
          description: Company-specific
          maxLength: 20
        nationalId:
          type:
            - string
            - 'null'
          description: Person-specific
          maxLength: 100
        nationalIdLast4:
          type:
            - string
            - 'null'
          minLength: 4
          maxLength: 4
        dateOfBirth:
          type:
            - string
            - 'null'
          format: date-time
        personSnapshot:
          type:
            - array
            - 'null'
          items:
            type: string
        status:
          type:
            - string
            - 'null'
          description: Optional common fields
          enum:
            - prospect
            - active
            - inactive
            - archived
        onboardedAt:
          type:
            - string
            - 'null'
          format: date-time
        engagementType:
          type:
            - string
            - 'null'
          enum:
            - advisory
            - litigation
            - transactional
            - compliance
            - other
        taxResidenceCountryCode:
          type:
            - string
            - 'null'
          minLength: 2
          maxLength: 2
        vatNumber:
          type:
            - string
            - 'null'
          maxLength: 30
        lei:
          type:
            - string
            - 'null'
          maxLength: 20
        preferredLanguage:
          type:
            - string
            - 'null'
          minLength: 2
          maxLength: 2
        notes:
          type:
            - string
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
            maxLength: 50
        companySnapshot:
          type: object
          properties:
            registrationNumber:
              type:
                - string
                - 'null'
            name:
              type:
                - string
                - 'null'
            countryCode:
              type:
                - string
                - 'null'
              minLength: 2
              maxLength: 2
      required:
        - type
        - displayName
        - countryCode
      title: StoreClientRequest
    StoreConsentV1Request:
      type: object
      description: |-
        Validates the body of POST accounttracking/v1/consents.

        Accepts camelCase external names. The controller maps these to the
        snake_case parameters expected by ConsentManager::createConsent().

        Scope values are validated against the allowed set per integration.

        Authorization enforced by EntityPermissions in the controller.
      properties:
        integrationName:
          type: string
          enum:
            - Neonomics
            - CreditSafe
            - TestIntegration
          maxLength: 100
        purpose:
          type: string
          enum:
            - account_access
            - transaction_history
            - balance_inquiry
            - credit_check
          maxLength: 100
        expiryDays:
          type: integer
          minimum: 1
          maximum: 90
        trackedAccountId:
          type:
            - integer
            - 'null'
        initialScopeType:
          type:
            - string
            - 'null'
        initialScopeId:
          type:
            - string
            - 'null'
        scope:
          type: array
          items:
            type: string
            enum:
              - accounts:read
              - transactions:read
              - balances:read
              - statements:read
              - profile:read
              - companies:read
            maxLength: 100
          minItems: 1
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
            maxLength: 255
      required:
        - integrationName
        - purpose
      title: StoreConsentV1Request
    StoreCounterpartV1Request:
      type: object
      description: >-
        Validates the body of POST accounttracking/v1/counterparts.


        Accepts both the v1 camelCase forms and the deprecated snake_case forms,

        so existing consumers keep working during migration.


        counterpartIdentifier / counterpart_identifier is required — it is the

        unique external identifier for this counterpart (e.g. bank account
        number,

        organisation number).


        Authorization enforced by EntityPermissions in the controller.
      properties:
        counterpartIdentifier:
          type: string
          description: '── Required: identifier (accept both forms) ──────────────────'
          maxLength: 255
        counterpart_identifier:
          type: string
          maxLength: 255
        name:
          type:
            - string
            - 'null'
          description: ── Name ──────────────────────────────────────────────────────
          maxLength: 255
        counterpart_name:
          type:
            - string
            - 'null'
          maxLength: 255
        type:
          type:
            - string
            - 'null'
          description: ── Type ──────────────────────────────────────────────────────
          enum:
            - company
            - person
            - bank
            - government
            - unknown
        counterpart_type:
          type:
            - string
            - 'null'
          enum:
            - company
            - person
            - bank
            - government
            - unknown
        visibleToEntityType:
          type:
            - string
            - 'null'
          description: ── Visibility (camelCase) ─────────────────────────────────────
        visibleToEntityId:
          type:
            - string
            - 'null'
        visible_to_entity_type:
          type:
            - string
            - 'null'
          description: Deprecated snake_case forms
        visible_to_entity_id:
          type:
            - string
            - 'null'
        countryCode:
          type:
            - string
            - 'null'
          description: ── Rich fields ────────────────────────────────────────────────
          minLength: 2
          maxLength: 2
        country_code:
          type:
            - string
            - 'null'
          minLength: 2
          maxLength: 2
        accessScope:
          type:
            - string
            - 'null'
          enum:
            - private
            - user
            - group
            - tenant
            - global
        access_scope:
          type:
            - string
            - 'null'
          enum:
            - private
            - user
            - group
            - tenant
            - global
        confidenceScore:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
        confidence_score:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
        metadata:
          type:
            - array
            - 'null'
          description: ── Metadata (opaque blob) ─────────────────────────────────────
          items:
            type: string
      title: StoreCounterpartV1Request
    StoreDatasetProfileV1Request:
      type: object
      description: >-
        Validation for POST datasets/v1/profiles.


        Validates a snake_case request body. Auth is the route-level
        auth:sanctum gate.
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        scope:
          type: string
          enum:
            - global
            - entity
            - profession
        entity_id:
          type:
            - string
            - 'null'
        entity_type:
          type:
            - string
            - 'null'
        profession:
          type:
            - string
            - 'null'
        sub_profession:
          type:
            - string
            - 'null'
        subset_selection:
          type: array
          items:
            type: string
          minItems: 1
        provider_priorities:
          type:
            - array
            - 'null'
          items:
            type: string
        is_default:
          type: boolean
      required:
        - name
        - scope
        - subset_selection
      title: StoreDatasetProfileV1Request
    StoreEntityAddressRequest:
      type: object
      description: |-
        Validates entity address creation payload.
        Authorization is preserved at the route-group level (auth:sanctum).
        No EntityPermissions checks here — validation only.
      properties:
        addressType:
          type: string
          enum:
            - headquarters
            - branch
            - billing
            - shipping
            - home
            - work
            - other
        label:
          type:
            - string
            - 'null'
          maxLength: 100
        addressLine1:
          type: string
          maxLength: 255
        addressLine2:
          type:
            - string
            - 'null'
          maxLength: 255
        city:
          type: string
          maxLength: 100
        stateProvince:
          type:
            - string
            - 'null'
          maxLength: 100
        postalCode:
          type:
            - string
            - 'null'
          maxLength: 20
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
        isPrimary:
          type:
            - boolean
            - 'null'
      required:
        - addressType
        - addressLine1
        - city
        - countryCode
      title: StoreEntityAddressRequest
    StoreEntityContactRequest:
      type: object
      description: |-
        Validates entity contact creation payload.
        Authorization is preserved at the route-group level (auth:sanctum).
        No EntityPermissions checks here — validation only.
      properties:
        contactType:
          type: string
          enum:
            - email
            - phone
            - mobile
            - fax
            - website
            - linkedin
            - twitter
            - facebook
            - instagram
            - other
        contactValue:
          type: string
          maxLength: 255
        label:
          type:
            - string
            - 'null'
          maxLength: 100
        isPrimary:
          type:
            - boolean
            - 'null'
      required:
        - contactType
        - contactValue
      title: StoreEntityContactRequest
    StoreEntityMediaRequest:
      type: object
      description: |-
        Validates entity media upload payload.
        Authorization is preserved at the route-group level (auth:sanctum).
        No EntityPermissions checks here — validation only.

        NOTE: This request is used for multipart/form-data uploads.
        The api.idempotent middleware MUST NOT be applied to routes using
        this request — idempotency fingerprinting breaks on multipart streams.
      properties:
        file:
          type: string
          format: binary
          contentMediaType: application/octet-stream
          maxLength: 10240
        media_type:
          type: string
          description: 10 MB max
          enum:
            - avatar
            - logo
            - document
            - image
            - video
            - other
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
      required:
        - file
        - media_type
      title: StoreEntityMediaRequest
    StoreGroupRequest:
      type: object
      description: >-
        Validates group creation payload.

        Authorization is enforced by route middleware (entity.permission /
        entity.owner).

        index/store have no capability gate — any authenticated user may create
        a group.
      properties:
        name:
          type: string
          maxLength: 255
        slug:
          type:
            - string
            - 'null'
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        groupType:
          type:
            - string
            - 'null'
          enum:
            - department
            - team
            - workgroup
            - community
            - custom
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
        tenantId:
          type:
            - string
            - 'null'
        profile:
          type: object
          properties:
            displayName:
              type:
                - string
                - 'null'
              maxLength: 255
            description:
              type:
                - string
                - 'null'
            visibilityScope:
              type:
                - string
                - 'null'
              enum:
                - private
                - group
                - tenant
                - partner
                - global
      required:
        - name
      title: StoreGroupRequest
    StoreProjectRequest:
      type: object
      description: >-
        Validates project creation payload.

        Authorization enforced by route middleware (open — any authenticated
        user).
      properties:
        name:
          type: string
          maxLength: 255
        slug:
          type:
            - string
            - 'null'
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        projectCode:
          type:
            - string
            - 'null'
          maxLength: 50
        projectType:
          type:
            - string
            - 'null'
          enum:
            - audit
            - compliance
            - investigation
            - research
            - development
            - consulting
            - custom
        status:
          type:
            - string
            - 'null'
          enum:
            - draft
            - active
            - on_hold
            - completed
            - cancelled
        priority:
          type:
            - string
            - 'null'
          enum:
            - low
            - medium
            - high
            - critical
        startDate:
          type:
            - string
            - 'null'
          format: date-time
        endDate:
          type:
            - string
            - 'null'
          format: date-time
        deadlineDate:
          type:
            - string
            - 'null'
          format: date-time
        budget:
          type:
            - number
            - 'null'
          minimum: 0
        currencyCode:
          type:
            - string
            - 'null'
          minLength: 3
          maxLength: 3
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
        tenantId:
          type:
            - string
            - 'null'
        groupId:
          type:
            - string
            - 'null'
        profile:
          type: object
          properties:
            displayName:
              type:
                - string
                - 'null'
              maxLength: 255
            description:
              type:
                - string
                - 'null'
      required:
        - name
      title: StoreProjectRequest
    StoreScoringRequest:
      type: object
      description: >-
        Validates POST scoring/v1 (create a scoring check).


        Accepts camelCase fields from the client and maps them to the

        snake_case inputs expected by TwoRequest in the controller.


        Validation only — authorization enforced by EntityPermissions in the
        controller.
      properties:
        organizationNumber:
          type: string
        amount:
          type: number
          minimum: 0
      required:
        - organizationNumber
        - amount
      title: StoreScoringRequest
    StoreTeamRequest:
      type: object
      description: >-
        Validates payload for creating a new Team.


        Authorization is enforced IN THE CONTROLLER via
        EntityPermissions::authorize('team.create'),

        NOT here. Per project convention, Form Requests are validation-only.


        The team.create permission requires the 'team'
        entity_service_subscription

        on the tenant (requires_subscription=true on the 'team'
        EntityCapability).
      properties:
        name:
          type: string
          maxLength: 255
        slug:
          type:
            - string
            - 'null'
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
      required:
        - name
      title: StoreTeamRequest
    StoreViewV1Request:
      type: object
      description: >-
        Validates the body of POST accounttracking/v1/views.


        Accepts camelCase external names. The controller maps these to the

        snake_case columns on MergedAccountView.


        accountIds references the integer PK of
        accounttracking_tracked_accounts.

        Cross-account visibility is filtered server-side — the exists: check
        only

        guards basic referential integrity.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        name:
          type: string
          maxLength: 120
        description:
          type:
            - string
            - 'null'
        defaultFromDate:
          type:
            - string
            - 'null'
          format: date
        defaultToDate:
          type:
            - string
            - 'null'
          format: date
        defaultBucket:
          type:
            - string
            - 'null'
          enum:
            - auto
            - day
            - week
            - month
        accountIds:
          type: array
          items:
            type: integer
          minItems: 1
          maxItems: 50
      required:
        - name
        - accountIds
      title: StoreViewV1Request
    SubscribeV1Request:
      type: object
      description: >-
        V1 Form Request for POST productmanagement/v1/subscriptions.


        Validation only — authorization is handled in the controller via
        EntityPermissions::authorize().

        Accepts either `packageSlug` (preferred, human-readable) or `packageId`
        (UUID, unambiguous).

        At least one must be present.
      properties:
        packageSlug:
          type: string
          maxLength: 191
        packageId:
          type: string
          format: uuid
        metadata:
          type: array
          items:
            type: string
      title: SubscribeV1Request
    SubscriptionV1Resource:
      type: object
      properties:
        id:
          type: string
        entityType:
          type: string
        entityId:
          type: string
        packageId:
          type: string
        isActive:
          type: boolean
        source:
          type: string
        assignedBy:
          type:
            - integer
            - 'null'
        startsAt:
          type:
            - string
            - 'null'
        expiresAt:
          type:
            - string
            - 'null'
        autoRenew:
          type: boolean
        metadata:
          type:
            - array
            - 'null'
          items: {}
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
        package:
          $ref: '#/components/schemas/PackageV1Resource'
      required:
        - id
        - entityType
        - entityId
        - packageId
        - isActive
        - source
        - assignedBy
        - startsAt
        - expiresAt
        - autoRenew
        - metadata
        - createdAt
        - updatedAt
      title: SubscriptionV1Resource
    SyncTransactionsV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/accounts/{accountId}/sync-transactions.


        When background=true the controller dispatches a background sync job and

        returns 202. When background=false (default) it runs synchronously and

        returns 200 with a syncedCount.


        This endpoint does not support the Idempotency-Key header.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        background:
          type: boolean
        filter:
          type: object
          properties:
            fromDate:
              type: string
              format: date
            toDate:
              type: string
              format: date
            scope:
              type: string
              enum:
                - organization
                - person
      title: SyncTransactionsV1Request
    TeamResource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        metadata:
          type: string
        isActive:
          type: string
        createdBy:
          type: string
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - name
        - slug
        - description
        - metadata
        - isActive
        - createdBy
        - createdAt
        - updatedAt
      title: TeamResource
    TrackSessionAccountsV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/sessions/{sessionUuid}/track.


        Confirms which discovered accounts from the session to begin tracking.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        accountIds:
          type: array
          items:
            type: string
          minItems: 1
        visibility:
          type: object
          description: >-
            Optional visibility configuration (privacy-first — default:
            self-restricted)
          properties:
            shared:
              type: boolean
            visibleTo:
              type: object
              properties:
                type:
                  type: string
                id:
                  type: string
      required:
        - accountIds
      title: TrackSessionAccountsV1Request
    TrackedAccount:
      type: object
      properties:
        id:
          type: integer
        physical_account_id:
          type:
            - integer
            - 'null'
        owner_entity_id:
          type:
            - string
            - 'null'
        owner_entity_type:
          type:
            - string
            - 'null'
        scope_entity_id:
          type:
            - string
            - 'null'
        scope_entity_type:
          type:
            - string
            - 'null'
        created_by:
          type:
            - integer
            - 'null'
        name:
          type: string
        number:
          type: string
        bank_name:
          type: string
        bank_id:
          type:
            - string
            - 'null'
        bic:
          type:
            - string
            - 'null'
        owner_name:
          type: string
        countrycode:
          type:
            - string
            - 'null'
        bban:
          type:
            - string
            - 'null'
        status:
          type:
            - string
            - 'null'
        reference_id:
          type:
            - string
            - 'null'
        last_transaction_sync:
          type:
            - string
            - 'null'
          format: date-time
        last_sync_error:
          type:
            - string
            - 'null'
        last_sync_error_at:
          type:
            - string
            - 'null'
          format: date-time
        tracking_start_date:
          type:
            - string
            - 'null'
          format: date-time
        auto_sync_enabled:
          type: boolean
        counterpart_scanning_enabled:
          type: boolean
        blacklist_checking_enabled:
          type: boolean
        account_intelligence_enabled:
          type: boolean
        metadata:
          type:
            - array
            - 'null'
          items: {}
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        partner_account_status:
          type:
            - string
            - 'null'
      required:
        - id
        - physical_account_id
        - owner_entity_id
        - owner_entity_type
        - scope_entity_id
        - scope_entity_type
        - created_by
        - name
        - number
        - bank_name
        - bank_id
        - bic
        - owner_name
        - countrycode
        - bban
        - status
        - reference_id
        - last_transaction_sync
        - last_sync_error
        - last_sync_error_at
        - tracking_start_date
        - auto_sync_enabled
        - counterpart_scanning_enabled
        - blacklist_checking_enabled
        - account_intelligence_enabled
        - metadata
        - created_at
        - updated_at
        - partner_account_status
      title: TrackedAccount
    UpdateAccountSettingsV1Request:
      type: object
      description: |-
        Validates the body of PATCH accounttracking/v1/accounts/{id}/settings.

        Accepts camelCase external names. The controller maps these to the
        snake_case column names expected by AccountSettingsService.

        Authorization enforced by EntityPermissions in the controller.
      properties:
        autoSyncEnabled:
          type: boolean
        counterpartScanningEnabled:
          type: boolean
        blacklistCheckingEnabled:
          type: boolean
        accountIntelligenceEnabled:
          type: boolean
        analysisApproved:
          type: boolean
          description: |-
            LEX-121: user approval for transaction analysis. Deliberately NOT
            in mappedSettings(): it targets the shared PhysicalAccount, not a
            TrackedAccount column — the controller routes it to
            AccountSettingsService::setAnalysisApproval() with user attribution.
      title: UpdateAccountSettingsV1Request
    UpdateAppRequest:
      type: object
      description: |-
        Validates the payload for updating an App (name/description/status).

        Authorization is enforced by the `entity.permission:app,apps.manage`
        route middleware. This class is validation-only.
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - active
            - suspended
      title: UpdateAppRequest
    UpdateCaseRequest:
      type: object
      description: >-
        Validates the payload for updating an existing LegalCase.


        Supports both PUT (full replace — all non-readonly fields must be
        present)

        and PATCH (partial update — only sent fields change, enforced by
        `sometimes`).


        clientId cannot be changed after creation (cases are tied to a client
        for life)

        and is intentionally excluded.


        caseIdDisplay is server-generated and cannot be changed after creation.


        Authorization stays in the controller via EntityPermissions::check(...,
        'case.update').

        This class is validation-only.
      properties:
        name:
          type: string
          maxLength: 255
        caseType:
          type: string
          enum:
            - m_a
            - bankruptcy
            - litigation
            - compliance
            - due_diligence
            - other
        status:
          type: string
          enum:
            - draft
            - open
            - on_hold
            - closed
            - archived
        openedAt:
          type:
            - string
            - 'null'
          format: date-time
        closedAt:
          type:
            - string
            - 'null'
          format: date-time
        targetCompletionDate:
          type:
            - string
            - 'null'
          format: date-time
        description:
          type:
            - string
            - 'null'
        notes:
          type:
            - string
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
            maxLength: 50
      title: UpdateCaseRequest
    UpdateClientRequest:
      type: object
      description: >-
        Validates the payload for updating an existing Client.


        Supports both PUT (full replace — all non-readonly fields must be
        present)

        and PATCH (partial update — only sent fields change, enforced by
        `sometimes`).


        The `type` field cannot be changed after creation and is intentionally

        excluded from this request.


        Authorization stays in the controller via EntityPermissions::check(...,
        'client.update').

        This class is validation-only.
      properties:
        displayName:
          type: string
          maxLength: 255
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
        registrationNumber:
          type:
            - string
            - 'null'
          description: Company fields
          maxLength: 20
        companySnapshot:
          type:
            - array
            - 'null'
          items:
            type: string
        nationalId:
          type:
            - string
            - 'null'
          description: Person fields
          maxLength: 100
        nationalIdLast4:
          type:
            - string
            - 'null'
          minLength: 4
          maxLength: 4
        dateOfBirth:
          type:
            - string
            - 'null'
          format: date-time
        personSnapshot:
          type:
            - array
            - 'null'
          items:
            type: string
        status:
          type: string
          description: Status / engagement
          enum:
            - prospect
            - active
            - inactive
            - archived
        onboardedAt:
          type:
            - string
            - 'null'
          format: date-time
        engagementType:
          type:
            - string
            - 'null'
          enum:
            - advisory
            - litigation
            - transactional
            - compliance
            - other
        taxResidenceCountryCode:
          type:
            - string
            - 'null'
          description: Tax / financial
          minLength: 2
          maxLength: 2
        vatNumber:
          type:
            - string
            - 'null'
          maxLength: 30
        lei:
          type:
            - string
            - 'null'
          maxLength: 20
        preferredLanguage:
          type:
            - string
            - 'null'
          description: Comms
          minLength: 2
          maxLength: 2
        notes:
          type:
            - string
            - 'null'
          description: Freeform
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
            maxLength: 50
      title: UpdateClientRequest
    UpdateConsentV1Request:
      type: object
      description: |-
        Validates the body of PATCH accounttracking/v1/consents/{consent}.

        Only metadata is updatable after creation; other fields are immutable
        once a consent is created and granted.

        Authorization enforced by EntityPermissions in the controller.
      properties:
        metadata:
          type: array
          items:
            type: string
            maxLength: 255
          minItems: 1
      required:
        - metadata
      title: UpdateConsentV1Request
    UpdateCounterpartV1Request:
      type: object
      description: |-
        Validates the body of PUT accounttracking/v1/counterparts/{counterpart}.

        All fields use 'sometimes' to support partial updates (the controller
        uses PUT semantics but the underlying service accepts sparse updates).

        Accepts both the v1 camelCase forms and the deprecated snake_case forms,
        to avoid breakage during migration.

        Authorization enforced by EntityPermissions in the controller.
      properties:
        name:
          type:
            - string
            - 'null'
          description: >-
            ── Name (camelCase + deprecated snake_case)
            ──────────────────────────────────
          maxLength: 255
        counterpart_name:
          type:
            - string
            - 'null'
          maxLength: 255
        displayName:
          type:
            - string
            - 'null'
          description: ── Display name ──────────────────────────────────────────────
          maxLength: 255
        display_name:
          type:
            - string
            - 'null'
          maxLength: 255
        type:
          type:
            - string
            - 'null'
          description: ── Type ──────────────────────────────────────────────────────
          enum:
            - company
            - person
            - bank
            - government
            - unknown
        counterpart_type:
          type:
            - string
            - 'null'
          enum:
            - company
            - person
            - bank
            - government
            - unknown
        countryCode:
          type:
            - string
            - 'null'
          description: ── Country ───────────────────────────────────────────────────
          minLength: 2
          maxLength: 2
        country_code:
          type:
            - string
            - 'null'
          minLength: 2
          maxLength: 2
        confidenceScore:
          type:
            - number
            - 'null'
          description: ── Confidence ────────────────────────────────────────────────
          minimum: 0
          maximum: 1
        confidence_score:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
        metadata:
          type:
            - array
            - 'null'
          description: ── Metadata (opaque blob) ─────────────────────────────────────
          items:
            type: string
      title: UpdateCounterpartV1Request
    UpdateCredentialsV1Request:
      type: object
      description: >-
        V1 Form Request for PUT
        productmanagement/v1/products/{slug}/credentials.


        Validation only — authorization is handled in the controller via
        EntityPermissions::authorize().

        Accepts camelCase `integrationId` (optional, required when multiple
        integrations are attached).
      properties:
        credentialType:
          type: string
          maxLength: 100
        integrationId:
          type: string
          maxLength: 36
        credentials:
          type: array
          items:
            type: string
          minItems: 1
      required:
        - credentials
      title: UpdateCredentialsV1Request
    UpdateDatasetProfileV1Request:
      type: object
      description: >-
        Validation for PUT datasets/v1/profiles/{id}.


        Validates a snake_case request body. Auth is the route-level
        auth:sanctum gate.
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        subset_selection:
          type: array
          items:
            type: string
          minItems: 1
        provider_priorities:
          type:
            - array
            - 'null'
          items:
            type: string
        is_active:
          type: boolean
        is_default:
          type: boolean
      title: UpdateDatasetProfileV1Request
    UpdateEntityAddressRequest:
      type: object
      description: |-
        Validates entity address update payload.
        Authorization is preserved at the route-group level (auth:sanctum).
        No EntityPermissions checks here — validation only.
        Uses 'sometimes' for all fields to support PATCH semantics.
      properties:
        addressType:
          type: string
          enum:
            - headquarters
            - branch
            - billing
            - shipping
            - home
            - work
            - other
        label:
          type:
            - string
            - 'null'
          maxLength: 100
        addressLine1:
          type: string
          maxLength: 255
        addressLine2:
          type:
            - string
            - 'null'
          maxLength: 255
        city:
          type: string
          maxLength: 100
        stateProvince:
          type:
            - string
            - 'null'
          maxLength: 100
        postalCode:
          type:
            - string
            - 'null'
          maxLength: 20
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
        isPrimary:
          type:
            - boolean
            - 'null'
        isActive:
          type:
            - boolean
            - 'null'
      title: UpdateEntityAddressRequest
    UpdateEntityContactRequest:
      type: object
      description: |-
        Validates entity contact update payload.
        Authorization is preserved at the route-group level (auth:sanctum).
        No EntityPermissions checks here — validation only.
        Uses 'sometimes' for all fields to support PATCH semantics.
      properties:
        contactType:
          type: string
          enum:
            - email
            - phone
            - mobile
            - fax
            - website
            - linkedin
            - twitter
            - facebook
            - instagram
            - other
        contactValue:
          type: string
          maxLength: 255
        label:
          type:
            - string
            - 'null'
          maxLength: 100
        isPrimary:
          type:
            - boolean
            - 'null'
        isActive:
          type:
            - boolean
            - 'null'
      title: UpdateEntityContactRequest
    UpdateEntityProfileRequest:
      type: object
      description: |-
        Validates entity profile update payload.
        Authorization is preserved at the route-group level (auth:sanctum).
        No EntityPermissions checks here — validation only.
      properties:
        displayName:
          type:
            - string
            - 'null'
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        visibilityScope:
          type:
            - string
            - 'null'
          enum:
            - private
            - group
            - tenant
            - partner
            - global
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
      title: UpdateEntityProfileRequest
    UpdateGroupMemberRoleRequest:
      type: object
      description: |-
        Validates member role update payload for groups.
        Authorization enforced by route middleware (entity.role:group,admin).
      properties:
        role:
          type: string
          enum:
            - member
            - owner
            - admin
      required:
        - role
      title: UpdateGroupMemberRoleRequest
    UpdateGroupRequest:
      type: object
      description: >-
        Validates group update payload.

        Authorization enforced by route middleware
        (entity.permission:group,profiles.update).
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        groupType:
          type: string
          enum:
            - department
            - team
            - workgroup
            - community
            - custom
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
        isActive:
          type: boolean
        profile:
          type: object
          properties:
            displayName:
              type:
                - string
                - 'null'
              maxLength: 255
            description:
              type:
                - string
                - 'null'
            visibilityScope:
              type:
                - string
                - 'null'
              enum:
                - private
                - group
                - tenant
                - partner
                - global
      title: UpdateGroupRequest
    UpdateMappingV1Request:
      type: object
      description: >-
        Validates the body of PUT accounttracking/v1/mappings/{id}.


        All fields use 'sometimes' to support partial updates.

        accountIdentifier and entityId are not updatable (immutable after
        creation).


        Authorization enforced by EntityPermissions in the controller.
      properties:
        ownershipType:
          type:
            - string
            - 'null'
          enum:
            - owner
            - authorized_signatory
            - joint_owner
        confidenceScore:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
        accessScope:
          type:
            - string
            - 'null'
          enum:
            - private
            - user
            - group
            - tenant
            - global
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
      title: UpdateMappingV1Request
    UpdatePersonalAccessTokenV1Request:
      type: object
      description: >-
        Validates PATCH users/v1/me/tokens/{tokenId}.


        At least one of name/expiresAt is required — enforced via
        withValidator()

        rather than required_without, so it doesn't interact with the per-field

        'sometimes' rules below (each field validates only when present, and

        'sometimes' + required_without have known ambiguous interplay).


        expiresAt rules mirror CreatePersonalAccessTokenV1Request: strictly
        future,

        no more than 365 days out — measured from NOW at request time, so a
        token

        can be repeatedly extended but never sit further than a year out from
        the

        moment of the PATCH.


        Validation only — authorization (human-user-only) and ownership are

        enforced in the controller/service.
      properties:
        name:
          type: string
          maxLength: 255
        expiresAt:
          type: string
          format: date-time
      title: UpdatePersonalAccessTokenV1Request
    UpdateProjectRequest:
      type: object
      description: >-
        Validates project update payload.

        Authorization enforced by route middleware
        (entity.permission:project,profiles.update).
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        projectType:
          type: string
          enum:
            - audit
            - compliance
            - investigation
            - research
            - development
            - consulting
            - custom
        status:
          type: string
          enum:
            - draft
            - active
            - on_hold
            - completed
            - cancelled
        priority:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
        startDate:
          type:
            - string
            - 'null'
          format: date-time
        endDate:
          type:
            - string
            - 'null'
          format: date-time
        deadlineDate:
          type:
            - string
            - 'null'
          format: date-time
        budget:
          type:
            - number
            - 'null'
          minimum: 0
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
        profile:
          type: object
          properties:
            displayName:
              type:
                - string
                - 'null'
              maxLength: 255
            description:
              type:
                - string
                - 'null'
      title: UpdateProjectRequest
    UpdateProjectUserRoleRequest:
      type: object
      description: |-
        Validates user-role update payload for projects.
        Authorization enforced by route middleware (entity.role:project,admin).
      properties:
        role:
          type: string
          enum:
            - assigned
            - owner
            - collaborator
            - admin
            - manager
            - member
            - viewer
      required:
        - role
      title: UpdateProjectUserRoleRequest
    UpdateScopeProfileV1Request:
      type: object
      description: >-
        Validates PUT users/v1/{id}/scope-profile.


        Mirrors the inline Validator::make() from
        UserController::updateScopeProfile().

        Requires 'metadata' as a non-empty array of key/value profile overrides
        for

        the current scope. Inner metadata keys are user-defined and passed
        through

        verbatim — they are NOT validated further.


        Validation only — authorization is enforced in the controller:
          - Self-update is always permitted (auth user == target user).
          - Third-party update requires EntityPermissions::can('members.manage').
      properties:
        metadata:
          type: array
          items:
            type: string
          minItems: 1
      required:
        - metadata
      title: UpdateScopeProfileV1Request
    UpdateTeamRequest:
      type: object
      description: >-
        Validates payload for updating an existing Team.


        Authorization is enforced by route middleware
        (entity.permission:group,team.update).

        authorize() returns true per project convention (validation-only Form
        Requests).
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type:
            - string
            - 'null'
        metadata:
          type:
            - array
            - 'null'
          items:
            type: string
        isActive:
          type: boolean
      title: UpdateTeamRequest
    UpdateTrackingStartDateV1Request:
      type: object
      description: >-
        Validates the body of PATCH
        accounttracking/v1/accounts/{id}/tracking-start-date.


        trackingStartDate must be a valid date. The controller maps this to the

        snake_case parameter expected by
        AccountSettingsService::updateTrackingStartDate().


        Authorization enforced by EntityPermissions in the controller.
      properties:
        trackingStartDate:
          type: string
          format: date-time
      required:
        - trackingStartDate
      title: UpdateTrackingStartDateV1Request
    UpdateViewV1Request:
      type: object
      description: |-
        Validates the body of PUT/PATCH accounttracking/v1/views/{view}.

        All fields use 'sometimes' — omitted fields are left unchanged.
        Passing accountIds as [] is rejected (an empty view is not valid;
        views can only become empty via account-side cascading deletes).

        Authorization enforced by EntityPermissions in the controller.
      properties:
        name:
          type: string
          maxLength: 120
        description:
          type:
            - string
            - 'null'
        defaultFromDate:
          type:
            - string
            - 'null'
          format: date
        defaultToDate:
          type:
            - string
            - 'null'
          format: date
        defaultBucket:
          type:
            - string
            - 'null'
          enum:
            - auto
            - day
            - week
            - month
        accountIds:
          type: array
          items:
            type: integer
          minItems: 1
          maxItems: 50
      title: UpdateViewV1Request
    UserAuthV1Resource:
      type: object
      properties:
        id: {}
        name:
          type: string
        email:
          type: string
        emailVerified:
          type: boolean
        emailVerifiedAt:
          type:
            - string
            - 'null'
        entityType:
          type: string
          const: user
        isAdmin:
          type: boolean
        avatarUrl:
          type:
            - string
            - 'null'
      required:
        - id
        - name
        - email
        - emailVerified
        - emailVerifiedAt
        - entityType
        - isAdmin
        - avatarUrl
      title: UserAuthV1Resource
    UserInvitationV1Resource:
      type: object
      properties:
        id:
          type: string
        parentEntityType:
          type: string
        parentEntityId:
          type: string
        childEntityType:
          type: string
        childEntityId:
          type: string
        relationshipType:
          type: string
        status:
          type: string
        invitationToken:
          type: string
        invitationTokenExpiresAt:
          type:
            - string
            - 'null'
        invitedAt:
          type:
            - string
            - 'null'
        acceptedAt:
          type:
            - string
            - 'null'
        rejectedAt:
          type:
            - string
            - 'null'
        suspendedAt:
          type:
            - string
            - 'null'
        invitedBy:
          type: string
        invitationMessage:
          type: string
        requestedRoleKey:
          type: string
        establishedBy:
          type: string
        establishedAt:
          type:
            - string
            - 'null'
        expiresAt:
          type:
            - string
            - 'null'
        metadata:
          type: string
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - parentEntityType
        - parentEntityId
        - childEntityType
        - childEntityId
        - relationshipType
        - status
        - invitationToken
        - invitationTokenExpiresAt
        - invitedAt
        - acceptedAt
        - rejectedAt
        - suspendedAt
        - invitedBy
        - invitationMessage
        - requestedRoleKey
        - establishedBy
        - establishedAt
        - expiresAt
        - metadata
        - createdAt
        - updatedAt
      title: UserInvitationV1Resource
    ValidateBicV1Request:
      type: object
      description: |-
        Validation for POST bank/v1/bic/validate.

        Requires `bic`.
      properties:
        bic:
          type: string
      required:
        - bic
      title: ValidateBicV1Request
    ValidateConsentV1Request:
      type: object
      description: >-
        Validates the body of POST
        accounttracking/v1/consents/{consent}/validate.


        Checks whether the consent is valid for a specific operation and scope
        set.

        Returns { data: { consentId, operation, isValid, consentStatus,
        validationTimestamp } }.


        Authorization enforced by EntityPermissions in the controller.
      properties:
        operation:
          type: string
          maxLength: 100
        requiredScopes:
          type: array
          items:
            type: string
            maxLength: 100
      required:
        - operation
      title: ValidateConsentV1Request
    ValidateIbanV1Request:
      type: object
      description: |-
        Validation for POST bank/v1/iban/validate.

        Requires `iban`.
      properties:
        iban:
          type: string
      required:
        - iban
      title: ValidateIbanV1Request
  responses:
    ValidationException:
      description: Validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: Stable snake_case error code from the shared registry.
                    enum:
                      - validation_failed
                  message:
                    type: string
                    description: Human-readable error message.
                  details:
                    type:
                      - object
                      - 'null'
                    description: >-
                      Present for validation_failed: field-level error messages,
                      keyed by external (camelCase) field name.
                required:
                  - code
                  - message
              meta:
                type: object
                properties:
                  requestId:
                    type: string
                    description: UUIDv7 request trace id.
                required:
                  - requestId
            required:
              - error
              - meta
    AuthenticationException:
      description: Unauthenticated
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: Stable snake_case error code from the shared registry.
                    enum:
                      - unauthenticated
                  message:
                    type: string
                    description: Human-readable error message.
                  details:
                    type:
                      - object
                      - 'null'
                    description: >-
                      Present for validation_failed: field-level error messages,
                      keyed by external (camelCase) field name.
                required:
                  - code
                  - message
              meta:
                type: object
                properties:
                  requestId:
                    type: string
                    description: UUIDv7 request trace id.
                required:
                  - requestId
            required:
              - error
              - meta
    AuthorizationException:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: Stable snake_case error code from the shared registry.
                    enum:
                      - forbidden
                  message:
                    type: string
                    description: Human-readable error message.
                  details:
                    type:
                      - object
                      - 'null'
                    description: >-
                      Present for validation_failed: field-level error messages,
                      keyed by external (camelCase) field name.
                required:
                  - code
                  - message
              meta:
                type: object
                properties:
                  requestId:
                    type: string
                    description: UUIDv7 request trace id.
                required:
                  - requestId
            required:
              - error
              - meta
    ModelNotFoundException:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: Stable snake_case error code from the shared registry.
                    enum:
                      - not_found
                  message:
                    type: string
                    description: Human-readable error message.
                  details:
                    type:
                      - object
                      - 'null'
                    description: >-
                      Present for validation_failed: field-level error messages,
                      keyed by external (camelCase) field name.
                required:
                  - code
                  - message
              meta:
                type: object
                properties:
                  requestId:
                    type: string
                    description: UUIDv7 request trace id.
                required:
                  - requestId
            required:
              - error
              - meta
tags:
  - name: AuthV1
    x-displayName: Sessions
    description: >-
      Log in, refresh, and revoke bearer tokens, and inspect the current
      session.
  - name: RegistrationV1
    x-displayName: Registration
    description: Register new user accounts.
  - name: PasswordResetV1
    x-displayName: Password Reset
    description: Request and complete a password reset by email.
  - name: PasswordV1
    x-displayName: Password
    description: Change the authenticated user's password.
  - name: PersonalAccessTokenV1
    x-displayName: Personal Access Tokens
    description: Create and manage long-lived personal access tokens that act as the user.
  - name: AppV1
    x-displayName: Apps
    description: Create and manage machine-actor apps that hold scoped API access.
  - name: AppKeyV1
    x-displayName: API Keys
    description: Issue, rotate, and revoke an app's API keys (max 2 active).
  - name: AppClientCredentialV1
    x-displayName: Client Credentials
    description: Manage an app's OAuth2 client-credentials set.
  - name: AppRoleV1
    x-displayName: App Roles
    description: Grant and revoke an app's roles on a scope.
  - name: OAuthAuthorize
    x-displayName: Authorize
    description: The OAuth authorization-code entry point (browser redirect).
  - name: OAuthConsent
    x-displayName: Consent
    description: The consent screen shown when a user authorizes a connector.
  - name: OAuthToken
    x-displayName: Token
    description: >-
      Exchange client-credentials or an authorization code for a bearer token,
      or refresh an existing one.
  - name: OAuthRevocation
    x-displayName: Revocation
    description: >-
      Revoke an access or refresh token issued through the authorization-code
      flow (RFC 7009).
  - name: OAuthConsentManagement
    x-displayName: Connected Apps
    description: List and revoke the connectors a user has authorized.
  - name: EntityConnectionV1
    x-displayName: Entity Connections
    description: List and revoke the connections installed on the operating entity.
  - name: CompanyIntelligenceV1
    x-displayName: Company Intelligence
    description: >-
      Enriched company insights and the intelligence capabilities available to
      you.
  - name: CompanySearchV1
    x-displayName: Company Search
    description: Search for companies across supported registries.
  - name: CompanySubsetV1
    x-displayName: Company Data
    description: Detailed company information and data subsets.
  - name: CompanyJobV1
    x-displayName: Company Jobs
    description: Asynchronous company data-processing jobs and their status.
  - name: CompanyReportV1
    x-displayName: Company Reports
    description: Company reports and their generation.
  - name: ScoringV1
    x-displayName: Scoring
    description: Risk and compliance scores for companies.
  - name: BankLookupV1
    x-displayName: Bank Lookup
    description: Banks and their reference metadata.
  - name: BankIdentificationV1
    x-displayName: Bank Identification
    description: Identify the bank behind an account number or identifier.
  - name: BankUtilityV1
    x-displayName: Bank Utilities
    description: IBAN and BIC validation and construction helpers.
  - name: AccountV1
    x-displayName: Accounts
    description: Tracked bank accounts and their connections.
  - name: AccountReportV1
    x-displayName: Account Reports
    description: Reports generated from tracked account activity.
  - name: AccountSettingsV1
    x-displayName: Account Settings
    description: Per-account tracking configuration.
  - name: ConsentV1
    x-displayName: Consents
    description: PSD2 account-access consents and their status.
  - name: ConsentCallbackV1
    x-displayName: Consent Callbacks
    description: Provider callbacks that complete a consent flow.
  - name: SessionV1
    x-displayName: Discovery Sessions
    description: Account-discovery sessions for connecting new accounts.
  - name: CounterpartV1
    x-displayName: Counterparts
    description: Transaction counterparties linked to accounts.
  - name: TransactionV1
    x-displayName: Transactions
    description: Account transactions and their details.
  - name: TransactionCounterpartV1
    x-displayName: Transaction Counterparts
    description: Counterparties bound to individual transactions.
  - name: MappingV1
    x-displayName: Mappings
    description: Rules that map accounts and transactions to counterparts.
  - name: MergedViewV1
    x-displayName: Merged Views
    description: Consolidated, cross-account transaction views.
  - name: Client
    x-displayName: Clients
    description: Client records managed within a scope.
  - name: LegalCase
    x-displayName: Cases
    description: Legal cases and their lifecycle.
  - name: Team
    x-displayName: Teams
    description: Teams within a tenant.
  - name: Group
    x-displayName: Groups
    description: Entity groups used to organize structure and access.
  - name: Project
    x-displayName: Projects
    description: Projects that group related work.
  - name: EntityProfile
    x-displayName: Profiles
    description: Profile details attached to an entity.
  - name: EntityContact
    x-displayName: Contacts
    description: Contact records attached to an entity.
  - name: EntityMedia
    x-displayName: Media
    description: Files and media attached to an entity.
  - name: EntityAddress
    x-displayName: Addresses
    description: Postal and physical addresses attached to an entity.
  - name: EntityInvitation
    x-displayName: Invitations
    description: Invitations to join an entity.
  - name: ProductCatalogV1
    x-displayName: Products
    description: The catalog of available products.
  - name: PackageCatalogV1
    x-displayName: Packages
    description: The catalog of product packages.
  - name: ProductActivationV1
    x-displayName: Activations
    description: Product activations and their status.
  - name: ProductCredentialV1
    x-displayName: Product Credentials
    description: Credentials required to use a product.
  - name: SubscriptionV1
    x-displayName: Subscriptions
    description: Product and package subscriptions.
  - name: UserV1
    x-displayName: Users
    description: User accounts within a tenant.
  - name: UserProfileRolesV1
    x-displayName: User Roles
    description: A user's roles across scopes and profiles.
  - name: UserInvitationV1
    x-displayName: User Invitations
    description: Invitations addressed to the current user.
  - name: ScopeV1
    x-displayName: Scopes
    description: The scopes (tenant, group, project) a request can operate in.
  - name: EntityRoleAssignmentV1
    x-displayName: Role Assignments
    description: Roles assigned to users on entities.
  - name: EntityPermissionGrantV1
    x-displayName: Permission Grants
    description: Direct permission grants for users on entities.
  - name: EffectivePermissionsV1
    x-displayName: Effective Permissions
    description: Resolved, effective permissions for a user on an entity.
  - name: PermissionCheckV1
    x-displayName: Permission Checks
    description: Checks for whether an actor may perform an action.
  - name: MePermissionsV1
    x-displayName: My Permissions
    description: The current user's own permissions.
  - name: MeEntityPermissionsV1
    x-displayName: My Entity Permissions
    description: The current user's resolved permissions on a specific entity.
  - name: PermissionDefinitionsV1
    x-displayName: Permission Definitions
    description: The catalog of defined permissions.
  - name: RoleCatalogV1
    x-displayName: Roles
    description: The catalog of available roles.
  - name: EntityHierarchyV1
    x-displayName: Entity Hierarchy
    description: The hierarchy and relationships between entities.
  - name: DatasetV1
    x-displayName: Datasets
    description: Datasets and their subset types.
  - name: DatasetProfileV1
    x-displayName: Dataset Profiles
    description: Profiles describing dataset contents.
  - name: ServiceHealth
    x-displayName: Service Health
    description: Lightweight per-service health and version checks.
x-tagGroups:
  - name: Authentication
    tags:
      - AuthV1
      - RegistrationV1
      - PasswordResetV1
      - PasswordV1
      - PersonalAccessTokenV1
  - name: Apps & API Keys
    tags:
      - AppV1
      - AppKeyV1
      - AppClientCredentialV1
      - AppRoleV1
  - name: OAuth & Connectors
    tags:
      - OAuthAuthorize
      - OAuthConsent
      - OAuthToken
      - OAuthRevocation
      - OAuthConsentManagement
      - EntityConnectionV1
  - name: Company Intelligence
    tags:
      - CompanyIntelligenceV1
      - CompanySearchV1
      - CompanySubsetV1
      - CompanyJobV1
      - CompanyReportV1
      - ScoringV1
      - BankLookupV1
      - BankIdentificationV1
      - BankUtilityV1
  - name: Account Tracking
    tags:
      - AccountV1
      - AccountReportV1
      - AccountSettingsV1
      - ConsentV1
      - ConsentCallbackV1
      - SessionV1
      - CounterpartV1
      - TransactionV1
      - TransactionCounterpartV1
      - MappingV1
      - MergedViewV1
  - name: Entity Management
    tags:
      - Client
      - LegalCase
      - Team
      - Group
      - Project
      - EntityProfile
      - EntityContact
      - EntityMedia
      - EntityAddress
      - EntityInvitation
  - name: Product Management
    tags:
      - ProductCatalogV1
      - PackageCatalogV1
      - ProductActivationV1
      - ProductCredentialV1
      - SubscriptionV1
  - name: Access & Permissions
    tags:
      - UserV1
      - UserProfileRolesV1
      - UserInvitationV1
      - ScopeV1
      - EntityRoleAssignmentV1
      - EntityPermissionGrantV1
      - EffectivePermissionsV1
      - PermissionCheckV1
      - MePermissionsV1
      - MeEntityPermissionsV1
      - PermissionDefinitionsV1
      - RoleCatalogV1
      - EntityHierarchyV1
  - name: Data Registry
    tags:
      - DatasetV1
      - DatasetProfileV1
  - name: Platform
    tags:
      - ServiceHealth
