openapi: 3.1.0
info:
  title: Micron Delta Protocol
  version: 2026-06-11
  summary: Case operations infrastructure — judgment intake to audited recovery.
  description: |-
    One contract to run a high-stakes case end to end. Authority-gated, fully audited, webhook-native. Versioned by date: endpoint paths, event names, error codes, and domain gates are stable across releases.

    Rate limits are per API key: sandbox 25 req/s (burst 50), production 100 req/s (burst 200). Exceeding them returns 429 rate_limited with a Retry-After header; every response carries MD-RateLimit-Limit and MD-RateLimit-Remaining.
  contact:
    name: Micron Delta
    url: https://kineticpartners.org/api
servers:
  - url: https://api.microndelta.com
    description: Production (md_live_)
  - url: https://sandbox.api.microndelta.com
    description: Sandbox (md_test_) — full surface, no production data
tags:
  - name: Health
    description: Health and product metadata.
    x-md-family: Control Plane
  - name: Organizations
    description: Organizations, users, roles, and API key scopes.
    x-md-family: Control Plane
  - name: Webhook Endpoints
    description: Register HTTPS endpoints to receive signed event deliveries. Each endpoint has its own signing secret and event filter.
    x-md-family: Control Plane
  - name: Matters
    description: Recovery matters and campaign dashboards.
    x-md-family: Case Spine
  - name: Judgments
    description: Judgment intake, validation, deadlines, and enforcement plans.
    x-md-family: Case Spine
  - name: Claimants
    description: Claimant registry and recovery economics.
    x-md-family: Case Spine
  - name: Debtors
    description: Debtor/adversary profiles, graphs, and asset hypotheses.
    x-md-family: Case Spine
  - name: Relationships
    description: Exchange, issuer, counsel, vendor, and counterparty relationships.
    x-md-family: Case Spine
  - name: Attribution
    description: Wallet, entity, source, confidence, and attribution graph workflows.
    x-md-family: Attribution
  - name: Network Attribution
    description: Lawful IP/network auxiliary attribution signals.
    x-md-family: Attribution
  - name: Crypto
    description: Asset maps, timelines, exchange hypotheses, stablecoin exposure.
    x-md-family: Attribution
  - name: Claw
    description: "Claw campaigns: focus, expand, pressure, actions, boards."
    x-md-family: Enforcement
  - name: Packets
    description: Legal, exchange, sanctions, and recovery packet generation.
    x-md-family: Enforcement
  - name: Issuer Remediation
    description: Stablecoin freeze, burn/reissue, destination-wallet workflows.
    x-md-family: Enforcement
  - name: Sanctions
    description: OFAC/SDN/DPRK/Lazarus/TCO screening and blocked-property workflows.
    x-md-family: Compliance Gates
  - name: Monitoring
    description: Wallet watchlists, alert rules, movement alerts.
    x-md-family: Compliance Gates
  - name: Actions
    description: Operator action queue and task state.
    x-md-family: Operations & Proof
  - name: Ledger
    description: Recovery events, remittance events, waterfalI calculations.
    x-md-family: Operations & Proof
  - name: Reports
    description: Executive, counsel, claimant, and operator reports.
    x-md-family: Operations & Proof
  - name: Audit
    description: Immutable event history and export trails.
    x-md-family: Operations & Proof
  # ── v2 Roadmap (coming soon) ──────────────────────────────
  - name: Documents
    description: "[Coming soon] Document vault: upload, tag, attach to matters, chain-of-custody tracking."
    x-md-family: Case Spine
    x-md-status: planned
  - name: Filings
    description: "[Coming soon] Court filing generation from matter data: discovery orders, turnover motions, contempt motions. Export as PDF."
    x-md-family: Enforcement
    x-md-status: planned
  - name: Fees
    description: "[Coming soon] Fee and cost tracking: attorney fees, receiver fees, expert costs. Ties into Ledger for court accountings."
    x-md-family: Operations & Proof
    x-md-status: planned
  - name: Batch
    description: "[Coming soon] Batch operations: bulk debtor import, bulk sanctions screening, bulk wallet import."
    x-md-family: Control Plane
    x-md-status: planned
  - name: Deadlines
    description: "[Coming soon] Deadline engine: statute of limitations, filing deadlines, response windows. Push alerts on approach."
    x-md-family: Case Spine
    x-md-status: planned
  - name: Jurisdictions
    description: "[Coming soon] Multi-jurisdiction enforcement paths: domestication of foreign judgments, cross-border coordination."
    x-md-family: Enforcement
    x-md-status: planned
  - name: Collaboration
    description: "[Coming soon] Shared matters: multi-party access with scoped permissions. Receiver shares read-only with court, read-write with counsel."
    x-md-family: Control Plane
    x-md-status: planned
  - name: Insurance
    description: "[Coming soon] Insurance and bond tracking: receiver bonds, fidelity insurance, errors and omissions."
    x-md-family: Case Spine
    x-md-status: planned
paths:
  /v1/health:
    get:
      operationId: getHealth
      summary: Health check
      description: Returns service status and API version.
      tags:
        - Health
      security:
        - protocol_key:
            - health:read
      x-md-scope: health:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  version:
                    type: string
                  environment:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
              example:
                status: ok
                version: string
                environment: string
                timestamp: 2026-06-01T12:00:00Z
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/capabilities:
    get:
      operationId: listCapabilities
      summary: List capabilities
      description: Returns available API modules, environments, enabled feature flags, and access posture.
      tags:
        - Health
      security:
        - protocol_key:
            - capabilities:read
      x-md-scope: capabilities:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  capabilities:
                    type: array
                    items:
                      type: string
                  modules:
                    type: array
                    items:
                      type: string
                  environments:
                    type: array
                    items:
                      type: string
                  notes:
                    type: string
              example:
                capabilities:
                  - string
                modules:
                  - string
                environments:
                  - string
                notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/organizations:
    post:
      operationId: createOrganization
      summary: Create organization
      description: Creates an organization tenant for internal, counsel, recovery operator, or partner use.
      tags:
        - Organizations
      security:
        - protocol_key:
            - org:write
      x-md-scope: org:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
                retention_policy:
                  type: string
            example:
              name: string
              type: string
              retention_policy: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
              example:
                organization_id: string
                name: string
                type: meridian_internal
                created_at: 2026-06-01T12:00:00Z
                features:
                  - string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listOrganizations
      summary: List organizations
      description: Lists organizations accessible to the caller.
      tags:
        - Organizations
      security:
        - protocol_key:
            - org:read
      x-md-scope: org:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        organization_id:
                          type: string
                        name:
                          type: string
                        type:
                          type: string
                        created_at:
                          type: string
                        features:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - organization_id: ...
                    name: ...
                    type: ...
                    created_at: ...
                    features: ...
                has_more: false
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
  /v1/organizations/{organization_id}:
    get:
      operationId: getOrganization
      summary: Get organization
      description: Gets an organization and feature flags.
      tags:
        - Organizations
      security:
        - protocol_key:
            - org:read
      x-md-scope: org:read
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
              example:
                organization_id: string
                name: string
                type: meridian_internal
                created_at: 2026-06-01T12:00:00Z
                features:
                  - string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: updateOrganization
      summary: Update organization
      description: Updates organization settings and retention defaults.
      tags:
        - Organizations
      security:
        - protocol_key:
            - org:write
      x-md-scope: org:write
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                retention_policy:
                  type: string
                features:
                  type: array
                  items:
                    type: string
            example:
              name: string
              retention_policy: string
              features:
                - string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
              example:
                organization_id: string
                name: string
                type: meridian_internal
                created_at: 2026-06-01T12:00:00Z
                features:
                  - string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/organizations/{organization_id}/api-keys:
    post:
      operationId: issueApiKey
      summary: Issue API key
      description: Issues a scoped API key for sandbox or approved production workflows.
      tags:
        - Organizations
      security:
        - protocol_key:
            - keys:write
      x-md-scope: keys:write
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                environment:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
                matter_ids:
                  type: array
                  items:
                    type: string
                expires_at:
                  type: string
                  format: date-time
            example:
              name: string
              environment: sandbox
              scopes:
                - string
              matter_ids:
                - string
              expires_at: 2026-06-01T12:00:00Z
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  key_id:
                    type: string
                  secret_once:
                    type: string
                  environment:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                  created_at:
                    type: string
                    format: date-time
              example:
                key_id: string
                secret_once: string
                environment: string
                scopes:
                  - string
                created_at: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listApiKeys
      summary: List API keys
      description: Lists API keys and status metadata without revealing secret material.
      tags:
        - Organizations
      security:
        - protocol_key:
            - keys:read
      x-md-scope: keys:read
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        key_id:
                          type: string
                        name:
                          type: string
                        environment:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                        status:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - key_id: string
                    name: string
                    environment: string
                    scopes:
                      - ...
                    status: string
                has_more: false
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/organizations/{organization_id}/users:
    post:
      operationId: inviteUser
      summary: Invite user
      description: Invites a user and assigns role/matter permissions.
      tags:
        - Organizations
      security:
        - protocol_key:
            - users:write
      x-md-scope: users:write
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                roles:
                  type: array
                  items:
                    type: string
                name:
                  type: string
                matter_ids:
                  type: array
                  items:
                    type: string
            example:
              email: string
              roles:
                - string
              name: string
              matter_ids:
                - string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                  email:
                    type: string
                  name:
                    type: string
                  roles:
                    type: array
                    items:
                      type: string
                  matter_ids:
                    type: array
                    items:
                      type: string
              example:
                user_id: string
                email: string
                name: string
                roles:
                  - string
                matter_ids:
                  - string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listUsers
      summary: List users
      description: Lists users in an organization.
      tags:
        - Organizations
      security:
        - protocol_key:
            - users:read
      x-md-scope: users:read
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        user_id:
                          type: string
                        email:
                          type: string
                        name:
                          type: string
                        roles:
                          type: string
                        matter_ids:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - user_id: ...
                    email: ...
                    name: ...
                    roles: ...
                    matter_ids: ...
                has_more: false
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/matters:
    post:
      operationId: createMatter
      summary: Create matter
      description: Creates a recovery matter and establishes the primary authority object container.
      tags:
        - Matters
      security:
        - protocol_key:
            - matters:write
      x-md-scope: matters:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                mode:
                  type: string
                lead_counsel:
                  type: string
                economics:
                  type: object
                  additionalProperties: true
                notes:
                  type: string
            example:
              name: string
              mode: string
              lead_counsel: string
              economics: {}
              notes: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Matter"
              example:
                matter_id: string
                name: string
                mode: small_judgment
                status: string
                organization_id: string
                lead_counsel: string
                economics: {}
                created_at: 2026-06-01T12:00:00Z
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listMatters
      summary: List matters
      description: Lists matters available to the caller, filtered by role and matter permission.
      tags:
        - Matters
      security:
        - protocol_key:
            - matters:read
      x-md-scope: matters:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        matter_id:
                          type: string
                        name:
                          type: string
                        mode:
                          type: string
                        status:
                          type: string
                        organization_id:
                          type: string
                        lead_counsel:
                          type: string
                        economics:
                          type: string
                        created_at:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - matter_id: ...
                    name: ...
                    mode: ...
                    status: ...
                    organization_id: ...
                    lead_counsel: ...
                    economics: ...
                    created_at: ...
                has_more: false
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
  /v1/matters/{matter_id}:
    get:
      operationId: getMatter
      summary: Get matter
      description: Gets a matter with summary status.
      tags:
        - Matters
      security:
        - protocol_key:
            - matters:read
      x-md-scope: matters:read
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Matter"
              example:
                matter_id: string
                name: string
                mode: small_judgment
                status: string
                organization_id: string
                lead_counsel: string
                economics: {}
                created_at: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: updateMatter
      summary: Update matter
      description: Updates matter metadata, mode, counsel, economics, and retention settings.
      tags:
        - Matters
      security:
        - protocol_key:
            - matters:write
      x-md-scope: matters:write
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                status:
                  type: string
                lead_counsel:
                  type: string
                economics:
                  type: object
                  additionalProperties: true
                retention_policy:
                  type: string
            example:
              name: string
              status: string
              lead_counsel: string
              economics: {}
              retention_policy: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Matter"
              example:
                matter_id: string
                name: string
                mode: small_judgment
                status: string
                organization_id: string
                lead_counsel: string
                economics: {}
                created_at: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/matters/{matter_id}/dashboard:
    get:
      operationId: getMatterDashboard
      summary: Get matter dashboard
      description: Returns command dashboard metrics for a matter.
      tags:
        - Matters
      security:
        - protocol_key:
            - matters:read
      x-md-scope: matters:read
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  matter_id:
                    type: string
                  judgment_value:
                    $ref: "#/components/schemas/Money"
                  known_crypto_exposure:
                    $ref: "#/components/schemas/Money"
                  open_actions:
                    type: integer
                  open_packets:
                    type: integer
                  alerts:
                    type: integer
                  recovery_events:
                    type: integer
                  meridian_economics:
                    $ref: "#/components/schemas/Money"
              example:
                matter_id: string
                judgment_value:
                  amount: 123.45
                  currency: string
                  valuation_time: 2026-06-01T12:00:00Z
                known_crypto_exposure:
                  amount: 123.45
                  currency: string
                  valuation_time: 2026-06-01T12:00:00Z
                open_actions: 123
                open_packets: 123
                alerts: 123
                recovery_events: 123
                meridian_economics:
                  amount: 123.45
                  currency: string
                  valuation_time: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/matters/{matter_id}/close:
    post:
      operationId: closeMatter
      summary: Close matter
      description: Closes a matter as paid, settled, exhausted, stayed, or administratively closed.
      tags:
        - Matters
      security:
        - protocol_key:
            - matters:write
      x-md-scope: matters:write
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                notes:
                  type: string
            example:
              reason: paid
              notes: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Matter"
              example:
                matter_id: string
                name: string
                mode: small_judgment
                status: string
                organization_id: string
                lead_counsel: string
                economics: {}
                created_at: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/judgments/intake:
    post:
      operationId: intakeJudgment
      summary: Intake judgment
      description: Creates a structured judgment record from entered fields and optional uploaded source references.
      tags:
        - Judgments
      security:
        - protocol_key:
            - judgments:write
      x-md-scope: judgments:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                court:
                  type: string
                case_number:
                  type: string
                jurisdiction:
                  type: string
                creditor:
                  type: string
                debtor:
                  type: string
                amount:
                  $ref: "#/components/schemas/Money"
                date_entered:
                  type: string
                  format: date
            example:
              matter_id: string
              court: string
              case_number: string
              jurisdiction: string
              creditor: string
              debtor: string
              amount:
                amount: 123.45
                currency: string
                valuation_time: 2026-06-01T12:00:00Z
              date_entered: 2026-06-01
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Judgment"
              example:
                judgment_id: string
                matter_id: string
                court: string
                case_number: string
                jurisdiction: string
                date_entered: 2026-06-01
                creditor: string
                debtor: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/judgments/{judgment_id}:
    get:
      operationId: getJudgment
      summary: Get judgment
      description: Gets judgment, validation, deadlines, linked matter, and balance summary.
      tags:
        - Judgments
      security:
        - protocol_key:
            - judgments:read
      x-md-scope: judgments:read
      parameters:
        - name: judgment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Judgment"
              example:
                judgment_id: string
                matter_id: string
                court: string
                case_number: string
                jurisdiction: string
                date_entered: 2026-06-01
                creditor: string
                debtor: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: updateJudgment
      summary: Update judgment
      description: Updates judgment metadata and review flags.
      tags:
        - Judgments
      security:
        - protocol_key:
            - judgments:write
      x-md-scope: judgments:write
      parameters:
        - name: judgment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                appeal_stay_status:
                  type: string
                bankruptcy_status:
                  type: string
                renewal_deadline:
                  type: string
                  format: date
                review_state:
                  type: object
                  properties:
                    review_required:
                      type: boolean
                    review_status:
                      type: string
                    review_owner:
                      type: string
                    review_notes:
                      type: string
            example:
              status: string
              appeal_stay_status: string
              bankruptcy_status: string
              renewal_deadline: 2026-06-01
              review_state:
                review_required: true
                review_status: not_required
                review_owner: string
                review_notes: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Judgment"
              example:
                judgment_id: string
                matter_id: string
                court: string
                case_number: string
                jurisdiction: string
                date_entered: 2026-06-01
                creditor: string
                debtor: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/judgments/{judgment_id}/validate:
    post:
      operationId: validateJudgment
      summary: Validate judgment readiness
      description: Runs authority, stay/appeal/bankruptcy, consumer/commercial, and required-document gates.
      tags:
        - Judgments
      security:
        - protocol_key:
            - judgments:validate
      x-md-scope: judgments:validate
      parameters:
        - name: judgment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                checks:
                  type: array
                  items:
                    type: string
                consumer_debt:
                  type: boolean
                bankruptcy_known:
                  type: boolean
                appeal_stay_known:
                  type: boolean
            example:
              checks:
                - string
              consumer_debt: true
              bankruptcy_known: true
              appeal_stay_known: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  judgment_id:
                    type: string
                  enforcement_ready:
                    type: boolean
                  review_required:
                    type: boolean
                  missing_items:
                    type: array
                    items:
                      type: string
                  gates:
                    type: array
                    items:
                      type: object
                      properties:
                        gate:
                          type: string
                        status:
                          type: string
                        reasons:
                          type: string
                        required_actions:
                          type: string
              example:
                judgment_id: string
                enforcement_ready: true
                review_required: true
                missing_items:
                  - string
                gates:
                  - gate: ...
                    status: ...
                    reasons: ...
                    required_actions: ...
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/judgments/{judgment_id}/deadlines:
    get:
      operationId: getJudgmentDeadlines
      summary: Get judgment deadlines
      description: Returns renewal, service, response, hearing, packet, and monitoring deadlines.
      tags:
        - Judgments
      security:
        - protocol_key:
            - judgments:read
      x-md-scope: judgments:read
      parameters:
        - name: judgment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        deadline_id:
                          type: string
                        type:
                          type: string
                        date:
                          type: string
                        owner:
                          type: string
                        status:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - deadline_id: ...
                    type: ...
                    date: ...
                    owner: ...
                    status: ...
                has_more: false
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/judgments/{judgment_id}/enforcement-profile:
    post:
      operationId: setEnforcementProfile
      summary: Set enforcement profile
      description: Sets Measured, Assertive, or Maximum Lawful posture after compliance gates.
      tags:
        - Judgments
      security:
        - protocol_key:
            - judgments:plan
      x-md-scope: judgments:plan
      parameters:
        - name: judgment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: string
                notes:
                  type: string
            example:
              profile: measured
              notes: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  judgment_id:
                    type: string
                  profile:
                    type: string
                  pressure_level:
                    type: integer
                  review_state:
                    type: object
                    properties:
                      review_required:
                        type: boolean
                      review_status:
                        type: string
                      review_owner:
                        type: string
                      review_notes:
                        type: string
              example:
                judgment_id: string
                profile: string
                pressure_level: 123
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/judgments/{judgment_id}/enforcement-plan:
    post:
      operationId: generateEnforcementPlan
      summary: Generate enforcement plan
      description: Generates a lawful action plan from judgment, debtor graph, crypto map, exchange opportunities, issuer opportunities, sanctions gates, and selected profile.
      tags:
        - Judgments
      security:
        - protocol_key:
            - judgments:plan
      x-md-scope: judgments:plan
      parameters:
        - name: judgment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: string
                constraints:
                  type: object
                  properties:
                    consumer_debt:
                      type: boolean
                    bankruptcy_known:
                      type: boolean
                    appeal_stay_known:
                      type: boolean
                    sanctions_review_required:
                      type: boolean
                known_wallets:
                  type: array
                  items:
                    type: string
                known_exchanges:
                  type: array
                  items:
                    type: string
            example:
              profile: measured
              constraints:
                consumer_debt: true
                bankruptcy_known: true
                appeal_stay_known: true
                sanctions_review_required: true
              known_wallets:
                - string
              known_exchanges:
                - string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan_id:
                    type: string
                  judgment_id:
                    type: string
                  profile:
                    type: string
                  review_required:
                    type: boolean
                  priority_actions:
                    type: array
                    items:
                      type: object
                      properties:
                        action_id:
                          type: string
                        matter_id:
                          type: string
                        campaign_id:
                          type: string
                        type:
                          type: string
                        title:
                          type: string
                        owner_id:
                          type: string
                        priority:
                          type: string
                        status:
                          type: string
                  blocked_actions:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        reason:
                          type: string
                  deadlines:
                    type: array
                    items:
                      type: object
                      properties:
                        deadline_id:
                          type: string
                        type:
                          type: string
                        date:
                          type: string
                        owner:
                          type: string
                        status:
                          type: string
                  gates:
                    type: array
                    items:
                      type: object
                      properties:
                        gate:
                          type: string
                        status:
                          type: string
                        reasons:
                          type: string
                        required_actions:
                          type: string
              example:
                plan_id: string
                judgment_id: string
                profile: string
                review_required: true
                priority_actions:
                  - action_id: ...
                    matter_id: ...
                    campaign_id: ...
                    type: ...
                    title: ...
                    owner_id: ...
                    priority: ...
                    status: ...
                blocked_actions:
                  - type: string
                    reason: string
                deadlines:
                  - deadline_id: ...
                    type: ...
                    date: ...
                    owner: ...
                    status: ...
                gates:
                  - gate: ...
                    status: ...
                    reasons: ...
                    required_actions: ...
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/matters/{matter_id}/claimants:
    post:
      operationId: addClaimant
      summary: Add claimant
      description: Adds claimant, creditor, assignee, or recovery interest holder to a matter.
      tags:
        - Claimants
      security:
        - protocol_key:
            - claimants:write
      x-md-scope: claimants:write
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                role:
                  type: string
                economics:
                  type: object
                  additionalProperties: true
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
            example:
              name: string
              role: string
              economics: {}
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claimant"
              example:
                claimant_id: string
                matter_id: string
                name: string
                role: creditor
                economics: {}
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listClaimants
      summary: List claimants
      description: Lists matter claimants and recovery economics.
      tags:
        - Claimants
      security:
        - protocol_key:
            - claimants:read
      x-md-scope: claimants:read
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        claimant_id:
                          type: string
                        matter_id:
                          type: string
                        name:
                          type: string
                        role:
                          type: string
                        economics:
                          type: string
                        review_state:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - claimant_id: ...
                    matter_id: ...
                    name: ...
                    role: ...
                    economics: ...
                    review_state: ...
                has_more: false
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/claimants/{claimant_id}:
    get:
      operationId: getClaimant
      summary: Get claimant
      description: Gets claimant and economics terms.
      tags:
        - Claimants
      security:
        - protocol_key:
            - claimants:read
      x-md-scope: claimants:read
      parameters:
        - name: claimant_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claimant"
              example:
                claimant_id: string
                matter_id: string
                name: string
                role: creditor
                economics: {}
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: updateClaimant
      summary: Update claimant
      description: Updates claimant terms and review status.
      tags:
        - Claimants
      security:
        - protocol_key:
            - claimants:write
      x-md-scope: claimants:write
      parameters:
        - name: claimant_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                economics:
                  type: object
                  additionalProperties: true
                review_state:
                  type: object
                  properties:
                    review_required:
                      type: boolean
                    review_status:
                      type: string
                    review_owner:
                      type: string
                    review_notes:
                      type: string
            example:
              name: string
              economics: {}
              review_state:
                review_required: true
                review_status: not_required
                review_owner: string
                review_notes: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claimant"
              example:
                claimant_id: string
                matter_id: string
                name: string
                role: creditor
                economics: {}
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/debtors:
    post:
      operationId: createDebtor
      summary: Create debtor/adversary
      description: Creates a debtor, adversary, nominee, entity, or related enforcement subject.
      tags:
        - Debtors
      security:
        - protocol_key:
            - debtors:write
      x-md-scope: debtors:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                type:
                  type: string
                legal_name:
                  type: string
                aliases:
                  type: array
                  items:
                    type: string
                identifiers:
                  type: object
                  additionalProperties: true
            example:
              matter_id: string
              type: string
              legal_name: string
              aliases:
                - string
              identifiers: {}
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Debtor"
              example:
                debtor_id: string
                matter_id: string
                type: individual
                legal_name: string
                aliases:
                  - string
                identifiers: {}
                wallets:
                  - string
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listDebtors
      summary: List debtors
      description: Lists debtors/adversaries available to the caller.
      tags:
        - Debtors
      security:
        - protocol_key:
            - debtors:read
      x-md-scope: debtors:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        debtor_id:
                          type: string
                        matter_id:
                          type: string
                        type:
                          type: string
                        legal_name:
                          type: string
                        aliases:
                          type: string
                        identifiers:
                          type: string
                        wallets:
                          type: string
                        review_state:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - debtor_id: ...
                    matter_id: ...
                    type: ...
                    legal_name: ...
                    aliases: ...
                    identifiers: ...
                    wallets: ...
                    review_state: ...
                has_more: false
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
  /v1/debtors/{debtor_id}:
    get:
      operationId: getDebtor
      summary: Get debtor/adversary
      description: Gets profile, aliases, wallets, assets, and review status.
      tags:
        - Debtors
      security:
        - protocol_key:
            - debtors:read
      x-md-scope: debtors:read
      parameters:
        - name: debtor_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Debtor"
              example:
                debtor_id: string
                matter_id: string
                type: individual
                legal_name: string
                aliases:
                  - string
                identifiers: {}
                wallets:
                  - string
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: updateDebtor
      summary: Update debtor/adversary
      description: Updates profile and linked identifiers.
      tags:
        - Debtors
      security:
        - protocol_key:
            - debtors:write
      x-md-scope: debtors:write
      parameters:
        - name: debtor_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                legal_name:
                  type: string
                aliases:
                  type: array
                  items:
                    type: string
                identifiers:
                  type: object
                  additionalProperties: true
                review_state:
                  type: object
                  properties:
                    review_required:
                      type: boolean
                    review_status:
                      type: string
                    review_owner:
                      type: string
                    review_notes:
                      type: string
            example:
              legal_name: string
              aliases:
                - string
              identifiers: {}
              review_state:
                review_required: true
                review_status: not_required
                review_owner: string
                review_notes: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Debtor"
              example:
                debtor_id: string
                matter_id: string
                type: individual
                legal_name: string
                aliases:
                  - string
                identifiers: {}
                wallets:
                  - string
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/debtors/{debtor_id}/graph:
    post:
      operationId: buildDebtorGraph
      summary: Build debtor graph
      description: Builds debtor/adversary graph with aliases, entities, wallets, service targets, public records, and source-linked claims.
      tags:
        - Debtors
      security:
        - protocol_key:
            - debtors:graph
      x-md-scope: debtors:graph
      parameters:
        - name: debtor_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                include_sources:
                  type: array
                  items:
                    type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
            example:
              include_sources:
                - string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  graph_id:
                    type: string
                  debtor_id:
                    type: string
                  nodes:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  edges:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  claims:
                    type: array
                    items:
                      type: object
                      properties:
                        claim_id:
                          type: string
                        matter_id:
                          type: string
                        subject:
                          type: string
                        predicate:
                          type: string
                        object:
                          type: string
                        source_type:
                          type: string
                        source_refs:
                          type: string
                        confidence:
                          type: string
                  review_state:
                    type: object
                    properties:
                      review_required:
                        type: boolean
                      review_status:
                        type: string
                      review_owner:
                        type: string
                      review_notes:
                        type: string
              example:
                graph_id: string
                debtor_id: string
                nodes:
                  - {}
                edges:
                  - {}
                claims:
                  - claim_id: ...
                    matter_id: ...
                    subject: ...
                    predicate: ...
                    object: ...
                    source_type: ...
                    source_refs: ...
                    confidence: ...
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/debtors/{debtor_id}/asset-hypotheses:
    post:
      operationId: createAssetHypotheses
      summary: Create asset hypotheses
      description: Generates source-linked asset hypotheses from debtor graph, judgment data, relationship data, and crypto attribution.
      tags:
        - Debtors
      security:
        - protocol_key:
            - debtors:graph
      x-md-scope: debtors:graph
      parameters:
        - name: debtor_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                asset_classes:
                  type: array
                  items:
                    type: string
                min_confidence:
                  type: number
            example:
              asset_classes:
                - string
              min_confidence: 123.45
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        hypothesis_id:
                          type: string
                        asset_type:
                          type: string
                        description:
                          type: string
                        confidence:
                          type: number
                        source_refs:
                          type: array
                          items:
                            type: string
              example:
                items:
                  - hypothesis_id: string
                    asset_type: string
                    description: string
                    confidence: 123.45
                    source_refs:
                      - ...
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/relationships:
    post:
      operationId: createRelationship
      summary: Create relationship
      description: Creates an exchange, issuer, counsel, vendor, LE-only channel, receiver, special master, claimant, or counterparty relationship object.
      tags:
        - Relationships
      security:
        - protocol_key:
            - relationships:write
      x-md-scope: relationships:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                counterparty_type:
                  type: string
                counterparty_name:
                  type: string
                channel_type:
                  type: string
                usable_by_meridian:
                  type: boolean
                usable_by_counsel:
                  type: boolean
                usable_by_law_enforcement:
                  type: boolean
                authorized_submitter_required:
                  type: boolean
                packet_types_supported:
                  type: array
                  items:
                    type: string
            example:
              counterparty_type: string
              counterparty_name: string
              channel_type: string
              usable_by_meridian: true
              usable_by_counsel: true
              usable_by_law_enforcement: true
              authorized_submitter_required: true
              packet_types_supported:
                - string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Relationship"
              example:
                relationship_id: string
                counterparty_type: exchange
                counterparty_name: string
                channel_type: string
                usable_by_meridian: true
                usable_by_counsel: true
                usable_by_law_enforcement: true
                authorized_submitter_required: true
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listRelationships
      summary: List relationships
      description: Lists relationship registry objects.
      tags:
        - Relationships
      security:
        - protocol_key:
            - relationships:read
      x-md-scope: relationships:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RelationshipList"
              example:
                object: list
                data:
                  - relationship_id: ...
                    counterparty_type: ...
                    counterparty_name: ...
                    channel_type: ...
                    usable_by_meridian: ...
                    usable_by_counsel: ...
                    usable_by_law_enforcement: ...
                    authorized_submitter_required: ...
                has_more: false
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
  /v1/relationships/{relationship_id}:
    get:
      operationId: getRelationship
      summary: Get relationship
      description: Gets channel type, allowed users, packet support, and contact history.
      tags:
        - Relationships
      security:
        - protocol_key:
            - relationships:read
      x-md-scope: relationships:read
      parameters:
        - name: relationship_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Relationship"
              example:
                relationship_id: string
                counterparty_type: exchange
                counterparty_name: string
                channel_type: string
                usable_by_meridian: true
                usable_by_counsel: true
                usable_by_law_enforcement: true
                authorized_submitter_required: true
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: updateRelationship
      summary: Update relationship
      description: Updates channel metadata, allowed use, and risk levels.
      tags:
        - Relationships
      security:
        - protocol_key:
            - relationships:write
      x-md-scope: relationships:write
      parameters:
        - name: relationship_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel_type:
                  type: string
                packet_types_supported:
                  type: array
                  items:
                    type: string
                risk_level:
                  type: string
                notes:
                  type: string
            example:
              channel_type: string
              packet_types_supported:
                - string
              risk_level: string
              notes: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Relationship"
              example:
                relationship_id: string
                counterparty_type: exchange
                counterparty_name: string
                channel_type: string
                usable_by_meridian: true
                usable_by_counsel: true
                usable_by_law_enforcement: true
                authorized_submitter_required: true
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/relationships/{relationship_id}/contact-log:
    post:
      operationId: addContactLog
      summary: Add contact log
      description: Records a relationship contact attempt, authorized sender, packet ID, outcome, and response state.
      tags:
        - Relationships
      security:
        - protocol_key:
            - relationships:write
      x-md-scope: relationships:write
      parameters:
        - name: relationship_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                authorized_sender:
                  type: string
                contact_type:
                  type: string
                packet_id:
                  type: string
                outcome:
                  type: string
                notes:
                  type: string
            example:
              matter_id: string
              authorized_sender: string
              contact_type: string
              packet_id: string
              outcome: string
              notes: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact_log_id:
                    type: string
                  relationship_id:
                    type: string
                  matter_id:
                    type: string
                  authorized_sender:
                    type: string
                  outcome:
                    type: string
                  created_at:
                    type: string
                    format: date-time
              example:
                contact_log_id: string
                relationship_id: string
                matter_id: string
                authorized_sender: string
                outcome: string
                created_at: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/relationships/counterparties/{counterparty_id}:
    get:
      operationId: getCounterpartyRelationships
      summary: Get counterparty relationships
      description: Gets all relationships, packets, and response history for an exchange, issuer, vendor, or other counterparty.
      tags:
        - Relationships
      security:
        - protocol_key:
            - relationships:read
      x-md-scope: relationships:read
      parameters:
        - name: counterparty_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RelationshipList"
              example:
                object: list
                data:
                  - relationship_id: ...
                    counterparty_type: ...
                    counterparty_name: ...
                    channel_type: ...
                    usable_by_meridian: ...
                    usable_by_counsel: ...
                    usable_by_law_enforcement: ...
                    authorized_submitter_required: ...
                has_more: false
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/attribution/wallets/import:
    post:
      operationId: importWallets
      summary: Import wallets
      description: Imports wallet addresses with matter, evidence, source, role, and confidence context.
      tags:
        - Attribution
      security:
        - protocol_key:
            - attribution:write
      x-md-scope: attribution:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: object
                    properties:
                      wallet_id:
                        type: string
                      address:
                        type: string
                      network:
                        type: string
                      role:
                        type: string
                      confidence:
                        type: string
                      source_refs:
                        type: string
            example:
              matter_id: string
              wallets:
                - wallet_id: ...
                  address: ...
                  network: ...
                  role: ...
                  confidence: ...
                  source_refs: ...
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  imported:
                    type: integer
                  wallets:
                    type: array
                    items:
                      type: object
                      properties:
                        wallet_id:
                          type: string
                        address:
                          type: string
                        network:
                          type: string
                        role:
                          type: string
                        confidence:
                          type: string
                        source_refs:
                          type: string
              example:
                imported: 123
                wallets:
                  - wallet_id: ...
                    address: ...
                    network: ...
                    role: ...
                    confidence: ...
                    source_refs: ...
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/attribution/graph:
    post:
      operationId: createAttributionGraph
      summary: Create attribution graph
      description: Creates or refreshes a source-linked graph of wallets, entities, exchanges, claims, contradictions, and confidence scores.
      tags:
        - Attribution
      security:
        - protocol_key:
            - attribution:graph
      x-md-scope: attribution:graph
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallet_ids:
                  type: array
                  items:
                    type: string
                include_contradictions:
                  type: boolean
            example:
              matter_id: string
              wallet_ids:
                - string
              include_contradictions: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttributionGraph"
              example:
                graph_id: string
                matter_id: string
                nodes:
                  - {}
                edges:
                  - {}
                claims:
                  - claim_id: ...
                    matter_id: ...
                    subject: ...
                    predicate: ...
                    object: ...
                    source_type: ...
                    source_refs: ...
                    confidence: ...
                confidence_matrix:
                  - claim_id: ...
                    score: ...
                    label: ...
                    basis: ...
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/attribution/claims:
    post:
      operationId: createAttributionClaim
      summary: Create attribution claim
      description: Creates a single attribution claim with subject, predicate, object, source basis, confidence, and review state.
      tags:
        - Attribution
      security:
        - protocol_key:
            - attribution:write
      x-md-scope: attribution:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                subject:
                  type: string
                predicate:
                  type: string
                object:
                  type: string
                source_type:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                confidence:
                  type: number
                basis:
                  type: array
                  items:
                    type: string
            example:
              matter_id: string
              subject: string
              predicate: string
              object: string
              source_type: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              confidence: 123.45
              basis:
                - string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  claim_id:
                    type: string
                  matter_id:
                    type: string
                  subject:
                    type: string
                  predicate:
                    type: string
                  object:
                    type: string
                  source_type:
                    type: string
                  source_refs:
                    type: array
                    items:
                      type: object
                      properties:
                        source_id:
                          type: string
                        source_type:
                          type: string
                        title:
                          type: string
                        uri:
                          type: string
                        hash:
                          type: string
                        chain_of_custody_id:
                          type: string
                        admissibility_notes:
                          type: string
                  confidence:
                    type: number
              example:
                claim_id: string
                matter_id: string
                subject: string
                predicate: string
                object: string
                source_type: string
                source_refs:
                  - source_id: ...
                    source_type: ...
                    title: ...
                    uri: ...
                    hash: ...
                    chain_of_custody_id: ...
                    admissibility_notes: ...
                confidence: 123.45
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/attribution/graphs/{graph_id}:
    get:
      operationId: getAttributionGraph
      summary: Get attribution graph
      description: Gets an attribution graph and source manifest.
      tags:
        - Attribution
      security:
        - protocol_key:
            - attribution:read
      x-md-scope: attribution:read
      parameters:
        - name: graph_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttributionGraph"
              example:
                graph_id: string
                matter_id: string
                nodes:
                  - {}
                edges:
                  - {}
                claims:
                  - claim_id: ...
                    matter_id: ...
                    subject: ...
                    predicate: ...
                    object: ...
                    source_type: ...
                    source_refs: ...
                    confidence: ...
                confidence_matrix:
                  - claim_id: ...
                    score: ...
                    label: ...
                    basis: ...
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/attribution/confidence-score:
    post:
      operationId: scoreAttribution
      summary: Score attribution
      description: Scores attribution claims based on evidence hierarchy, corroboration, contradictions, source type, and review status.
      tags:
        - Attribution
      security:
        - protocol_key:
            - attribution:score
      x-md-scope: attribution:score
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                claim_id:
                  type: string
                evidence_tier:
                  type: string
                corroboration:
                  type: array
                  items:
                    type: string
                contradictions:
                  type: array
                  items:
                    type: string
            example:
              claim_id: string
              evidence_tier: string
              corroboration:
                - string
              contradictions:
                - string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  claim_id:
                    type: string
                  score:
                    type: number
                  label:
                    type: string
                  basis:
                    type: array
                    items:
                      type: string
              example:
                claim_id: string
                score: 123.45
                label: weak_signal
                basis:
                  - string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/network-attribution/signals:
    post:
      operationId: addNetworkSignal
      summary: Add network attribution signal
      description: Adds lawful auxiliary IP/network/provider signal with source restrictions and confidence level.
      tags:
        - Network Attribution
      security:
        - protocol_key:
            - network:write
      x-md-scope: network:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                signal_type:
                  type: string
                source:
                  type: string
                wallet_address:
                  type: string
                legal_process_id:
                  type: string
                timestamp:
                  type: string
                  format: date-time
                raw_value_redacted:
                  type: string
                privacy_restrictions:
                  type: array
                  items:
                    type: string
            example:
              matter_id: string
              signal_type: string
              source: string
              wallet_address: string
              legal_process_id: string
              timestamp: 2026-06-01T12:00:00Z
              raw_value_redacted: string
              privacy_restrictions:
                - string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetworkAttribution"
              example:
                network_attribution_id: string
                matter_id: string
                wallet_address: string
                signal_type: exchange_login_ip
                source: string
                legal_process_id: string
                timestamp: 2026-06-01T12:00:00Z
                confidence_level: L0
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/network-attribution/correlate:
    post:
      operationId: correlateNetworkSignals
      summary: Correlate network signals
      description: Correlates wallet, exchange, provider, claimant, domain, cloud, and telemetry signals without treating IP as standalone proof.
      tags:
        - Network Attribution
      security:
        - protocol_key:
            - network:correlate
      x-md-scope: network:correlate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallet_ids:
                  type: array
                  items:
                    type: string
                signal_ids:
                  type: array
                  items:
                    type: string
            example:
              matter_id: string
              wallet_ids:
                - string
              signal_ids:
                - string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  matter_id:
                    type: string
                  correlations:
                    type: array
                    items:
                      type: object
                      properties:
                        subject:
                          type: string
                        signal_id:
                          type: string
                        confidence_level:
                          type: string
                        explanation:
                          type: string
                        review_required:
                          type: boolean
              example:
                matter_id: string
                correlations:
                  - subject: string
                    signal_id: string
                    confidence_level: string
                    explanation: string
                    review_required: true
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/network-attribution/{network_attribution_id}:
    get:
      operationId: getNetworkAttribution
      summary: Get network attribution
      description: Gets a network signal/correlation result with privacy restrictions and legal process provenance.
      tags:
        - Network Attribution
      security:
        - protocol_key:
            - network:read
      x-md-scope: network:read
      parameters:
        - name: network_attribution_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetworkAttribution"
              example:
                network_attribution_id: string
                matter_id: string
                wallet_address: string
                signal_type: exchange_login_ip
                source: string
                legal_process_id: string
                timestamp: 2026-06-01T12:00:00Z
                confidence_level: L0
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/crypto/asset-map:
    post:
      operationId: createCryptoAssetMap
      summary: Create crypto asset map
      description: "Maps known and suspected crypto exposure: wallets, token balances, transaction timelines, exchange hypotheses, stablecoins, NFTs, DeFi, bridges, and confidence scores."
      tags:
        - Crypto
      security:
        - protocol_key:
            - crypto:map
      x-md-scope: crypto:map
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                chains:
                  type: array
                  items:
                    type: string
                include_stablecoins:
                  type: boolean
                include_exchanges:
                  type: boolean
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
            example:
              matter_id: string
              wallets:
                - string
              chains:
                - string
              include_stablecoins: true
              include_exchanges: true
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CryptoAssetMap"
              example:
                map_id: string
                matter_id: string
                wallets:
                  - wallet_id: ...
                    address: ...
                    network: ...
                    role: ...
                    confidence: ...
                    source_refs: ...
                token_exposures:
                  - asset: string
                    network: string
                    amount: 123.45
                    usd_value: 123.45
                    wallet: string
                exchange_hypotheses:
                  - hypothesis_id: ...
                    exchange: ...
                    wallet: ...
                    basis: ...
                    confidence: ...
                    packet_readiness: ...
                    source_refs: ...
                stablecoin_exposure:
                  - issuer: ...
                    asset: ...
                    network: ...
                    wallet: ...
                    amount: ...
                    freeze_capability_notes: ...
                    remediation_candidates: ...
                    review_required: ...
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/crypto/transaction-timeline:
    post:
      operationId: createTransactionTimeline
      summary: Create transaction timeline
      description: Builds a source-linked transaction timeline for a wallet set, matter, token, chain, or target cluster.
      tags:
        - Crypto
      security:
        - protocol_key:
            - crypto:timeline
      x-md-scope: crypto:timeline
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                from:
                  type: string
                  format: date-time
                to:
                  type: string
                  format: date-time
            example:
              matter_id: string
              wallets:
                - string
              from: 2026-06-01T12:00:00Z
              to: 2026-06-01T12:00:00Z
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  timeline_id:
                    type: string
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        transaction_hash:
                          type: string
                        timestamp:
                          type: string
                          format: date-time
                        from_address:
                          type: string
                        to_address:
                          type: string
                        asset:
                          type: string
                        amount:
                          type: number
                        notes:
                          type: string
              example:
                timeline_id: string
                events:
                  - transaction_hash: string
                    timestamp: 2026-06-01T12:00:00Z
                    from_address: string
                    to_address: string
                    asset: string
                    amount: 123.45
                    notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/crypto/exchange-hypotheses:
    post:
      operationId: createExchangeHypotheses
      summary: Create exchange hypotheses
      description: Creates exchange/VASP off-ramp hypotheses with confidence, evidence, and packet readiness.
      tags:
        - Crypto
      security:
        - protocol_key:
            - crypto:exchange
      x-md-scope: crypto:exchange
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                min_confidence:
                  type: number
            example:
              matter_id: string
              wallets:
                - string
              min_confidence: 123.45
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        hypothesis_id:
                          type: string
                        exchange:
                          type: string
                        wallet:
                          type: string
                        basis:
                          type: string
                        confidence:
                          type: string
                        packet_readiness:
                          type: string
                        source_refs:
                          type: string
              example:
                items:
                  - hypothesis_id: ...
                    exchange: ...
                    wallet: ...
                    basis: ...
                    confidence: ...
                    packet_readiness: ...
                    source_refs: ...
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/crypto/stablecoin-exposure:
    post:
      operationId: analyzeStablecoinExposure
      summary: Analyze stablecoin exposure
      description: Identifies freeze-capable or issuer-remediation-relevant stablecoin exposure and packet opportunities.
      tags:
        - Crypto
      security:
        - protocol_key:
            - crypto:stablecoin
      x-md-scope: crypto:stablecoin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                assets:
                  type: array
                  items:
                    type: string
            example:
              matter_id: string
              wallets:
                - string
              assets:
                - string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        issuer:
                          type: string
                        asset:
                          type: string
                        network:
                          type: string
                        wallet:
                          type: string
                        amount:
                          type: string
                        freeze_capability_notes:
                          type: string
                        remediation_candidates:
                          type: string
                        review_required:
                          type: string
              example:
                items:
                  - issuer: ...
                    asset: ...
                    network: ...
                    wallet: ...
                    amount: ...
                    freeze_capability_notes: ...
                    remediation_candidates: ...
                    review_required: ...
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/crypto/asset-map/{map_id}:
    get:
      operationId: getCryptoAssetMap
      summary: Get crypto asset map
      description: Gets crypto asset map and source manifest.
      tags:
        - Crypto
      security:
        - protocol_key:
            - crypto:read
      x-md-scope: crypto:read
      parameters:
        - name: map_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CryptoAssetMap"
              example:
                map_id: string
                matter_id: string
                wallets:
                  - wallet_id: ...
                    address: ...
                    network: ...
                    role: ...
                    confidence: ...
                    source_refs: ...
                token_exposures:
                  - asset: string
                    network: string
                    amount: 123.45
                    usd_value: 123.45
                    wallet: string
                exchange_hypotheses:
                  - hypothesis_id: ...
                    exchange: ...
                    wallet: ...
                    basis: ...
                    confidence: ...
                    packet_readiness: ...
                    source_refs: ...
                stablecoin_exposure:
                  - issuer: ...
                    asset: ...
                    network: ...
                    wallet: ...
                    amount: ...
                    freeze_capability_notes: ...
                    remediation_candidates: ...
                    review_required: ...
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/claw/campaigns:
    post:
      operationId: createClawCampaign
      summary: Create Claw campaign
      description: Creates a lawful enforcement campaign around a judgment, target set, exchange/issuer opportunities, sanctions gates, and economics.
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:write
      x-md-scope: claw:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                mode:
                  type: string
                target_set:
                  type: object
                  additionalProperties: true
            example:
              matter_id: string
              judgment_id: string
              mode: string
              target_set: {}
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClawCampaign"
              example:
                campaign_id: string
                matter_id: string
                judgment_id: string
                mode: measured
                pressure_level: 123
                target_set: {}
                operator_state:
                  focus_score: 123.45
                  expand_queue: 123
                  next_claw_action: string
                gates:
                  - gate: ...
                    status: ...
                    reasons: ...
                    required_actions: ...
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listClawCampaigns
      summary: List Claw campaigns
      description: Lists Claw campaigns accessible to caller.
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:read
      x-md-scope: claw:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        campaign_id:
                          type: string
                        matter_id:
                          type: string
                        judgment_id:
                          type: string
                        mode:
                          type: string
                        pressure_level:
                          type: string
                        target_set:
                          type: string
                        operator_state:
                          type: string
                        gates:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - campaign_id: ...
                    matter_id: ...
                    judgment_id: ...
                    mode: ...
                    pressure_level: ...
                    target_set: ...
                    operator_state: ...
                    gates: ...
                has_more: false
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
  /v1/claw/campaigns/{campaign_id}:
    get:
      operationId: getClawCampaign
      summary: Get Claw campaign
      description: Gets campaign configuration, pressure level, action board, gates, and metrics.
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:read
      x-md-scope: claw:read
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClawCampaign"
              example:
                campaign_id: string
                matter_id: string
                judgment_id: string
                mode: measured
                pressure_level: 123
                target_set: {}
                operator_state:
                  focus_score: 123.45
                  expand_queue: 123
                  next_claw_action: string
                gates:
                  - gate: ...
                    status: ...
                    reasons: ...
                    required_actions: ...
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: updateClawCampaign
      summary: Update Claw campaign
      description: Updates campaign mode, target set, operator state, and review flags.
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:write
      x-md-scope: claw:write
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                target_set:
                  type: object
                  additionalProperties: true
                pressure_level:
                  type: integer
            example:
              mode: string
              target_set: {}
              pressure_level: 123
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClawCampaign"
              example:
                campaign_id: string
                matter_id: string
                judgment_id: string
                mode: measured
                pressure_level: 123
                target_set: {}
                operator_state:
                  focus_score: 123.45
                  expand_queue: 123
                  next_claw_action: string
                gates:
                  - gate: ...
                    status: ...
                    reasons: ...
                    required_actions: ...
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/claw/campaigns/{campaign_id}/focus:
    post:
      operationId: focusClaw
      summary: Focus Claw
      description: Ranks wallets, exchanges, issuers, packets, actions, and operator tasks by actionability.
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:operate
      x-md-scope: claw:operate
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                criteria:
                  type: array
                  items:
                    type: string
                weights:
                  type: object
                  additionalProperties: true
            example:
              criteria:
                - string
              weights: {}
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaign_id:
                    type: string
                  ranked_targets:
                    type: array
                    items:
                      type: object
                      properties:
                        target_type:
                          type: string
                        target_id:
                          type: string
                        focus_score:
                          type: number
                        reason:
                          type: string
              example:
                campaign_id: string
                ranked_targets:
                  - target_type: string
                    target_id: string
                    focus_score: 123.45
                    reason: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/claw/campaigns/{campaign_id}/expand:
    post:
      operationId: expandClaw
      summary: Expand Claw
      description: Adds lawful graph expansion leads, attribution leads, legal process targets, and counterparty opportunities.
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:operate
      x-md-scope: claw:operate
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                expansion_types:
                  type: array
                  items:
                    type: string
                max_leads:
                  type: integer
            example:
              expansion_types:
                - string
              max_leads: 123
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaign_id:
                    type: string
                  leads:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
              example:
                campaign_id: string
                leads:
                  - {}
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/claw/campaigns/{campaign_id}/pressure:
    post:
      operationId: setClawPressure
      summary: Set pressure level
      description: "Moves campaign across lawful pressure levels: observe, prepare, preserve, discover, freeze/block, seize/turn over, recover/distribute."
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:pressure
      x-md-scope: claw:pressure
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pressure_level:
                  type: integer
                reason:
                  type: string
                counsel_approval_id:
                  type: string
            example:
              pressure_level: 123
              reason: string
              counsel_approval_id: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClawCampaign"
              example:
                campaign_id: string
                matter_id: string
                judgment_id: string
                mode: measured
                pressure_level: 123
                target_set: {}
                operator_state:
                  focus_score: 123.45
                  expand_queue: 123
                  next_claw_action: string
                gates:
                  - gate: ...
                    status: ...
                    reasons: ...
                    required_actions: ...
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/claw/campaigns/{campaign_id}/actions:
    post:
      operationId: createClawAction
      summary: Create Claw action
      description: "Creates a campaign action: watch, packet, discovery, exchange, issuer, sanctions, legal process, ledger, or reporting task."
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:operate
      x-md-scope: claw:operate
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                title:
                  type: string
                owner_id:
                  type: string
                due_at:
                  type: string
                  format: date-time
                linked_packet_id:
                  type: string
                review_required:
                  type: boolean
            example:
              type: string
              title: string
              owner_id: string
              due_at: 2026-06-01T12:00:00Z
              linked_packet_id: string
              review_required: true
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                action_id: string
                matter_id: string
                campaign_id: string
                type: string
                title: string
                owner_id: string
                priority: string
                status: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/claw/campaigns/{campaign_id}/board:
    get:
      operationId: getClawBoard
      summary: Get Claw board
      description: Gets operator board with focus queue, expand queue, pressure state, legal packets, alerts, and blockers.
      tags:
        - Claw
      security:
        - protocol_key:
            - claw:read
      x-md-scope: claw:read
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaign:
                    type: object
                    properties:
                      campaign_id:
                        type: string
                      matter_id:
                        type: string
                      judgment_id:
                        type: string
                      mode:
                        type: string
                      pressure_level:
                        type: integer
                      target_set:
                        type: object
                        additionalProperties: true
                      operator_state:
                        type: object
                        properties:
                          focus_score:
                            type: string
                          expand_queue:
                            type: string
                          next_claw_action:
                            type: string
                      gates:
                        type: array
                        items:
                          type: string
                  focus_queue:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  expand_queue:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  packet_queue:
                    type: array
                    items:
                      type: object
                      properties:
                        packet_id:
                          type: string
                        matter_id:
                          type: string
                        type:
                          type: string
                        status:
                          type: string
                        authorized_sender:
                          type: string
                        review_state:
                          type: string
                        source_refs:
                          type: string
                        audit:
                          type: string
                  alerts:
                    type: array
                    items:
                      type: object
                      properties:
                        alert_id:
                          type: string
                        matter_id:
                          type: string
                        type:
                          type: string
                        severity:
                          type: string
                        status:
                          type: string
                        target:
                          type: string
                        reason:
                          type: string
                        created_at:
                          type: string
                  blockers:
                    type: array
                    items:
                      type: object
                      properties:
                        gate:
                          type: string
                        status:
                          type: string
                        reasons:
                          type: string
                        required_actions:
                          type: string
              example:
                campaign:
                  campaign_id: string
                  matter_id: string
                  judgment_id: string
                  mode: measured
                  pressure_level: 123
                  target_set: {}
                  operator_state:
                    focus_score: ...
                    expand_queue: ...
                    next_claw_action: ...
                  gates:
                    - ...
                focus_queue:
                  - {}
                expand_queue:
                  - {}
                packet_queue:
                  - packet_id: ...
                    matter_id: ...
                    type: ...
                    status: ...
                    authorized_sender: ...
                    review_state: ...
                    source_refs: ...
                    audit: ...
                alerts:
                  - alert_id: ...
                    matter_id: ...
                    type: ...
                    severity: ...
                    status: ...
                    target: ...
                    reason: ...
                    created_at: ...
                blockers:
                  - gate: ...
                    status: ...
                    reasons: ...
                    required_actions: ...
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/exchange-intercept:
    post:
      operationId: createExchangeInterceptPacket
      summary: Create exchange intercept packet
      description: Prepares a source-linked packet for exchange/VASP preservation, freeze, information request, turnover, or remittance workflows.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:write
      x-md-scope: packets:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/vasp-legal-process:
    post:
      operationId: createVaspLegalProcessPacket
      summary: Create VASP legal process packet
      description: Prepares counsel-reviewed subpoena, records request, preservation, or VASP response packet.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:write
      x-md-scope: packets:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/exchange-freeze:
    post:
      operationId: createExchangeFreezePacket
      summary: Create exchange freeze packet
      description: Prepares exchange freeze/hold request packet subject to court/counsel/authorized-channel review.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:write
      x-md-scope: packets:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/exchange-turnover:
    post:
      operationId: createExchangeTurnoverPacket
      summary: Create exchange turnover packet
      description: Prepares turnover request packet for court/counsel/exchange workflows.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:write
      x-md-scope: packets:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/turnover-workflow:
    post:
      operationId: createTurnoverWorkflowPacket
      summary: Create self-custody turnover workflow
      description: Prepares court-supervised self-custody turnover workflow with proof-of-control evidence and noncompliance tracker.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:write
      x-md-scope: packets:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/sanctions-review:
    post:
      operationId: createSanctionsReviewPacket
      summary: Create sanctions review packet
      description: Prepares OFAC/SDN/DPRK/Lazarus/TCO evidence packet and blocked-property review queue.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:write
      x-md-scope: packets:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SanctionsReview"
              example:
                review_id: string
                matter_id: string
                status: string
                blocked_property_analysis: string
                ofac_report_required: true
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/law-enforcement-referral:
    post:
      operationId: createLawEnforcementReferralPacket
      summary: Create law enforcement referral packet
      description: Prepares referral packet for authorized counsel/LE workflows. Does not impersonate or use LE-only channels.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:write
      x-md-scope: packets:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/{packet_id}:
    get:
      operationId: getPacket
      summary: Get packet
      description: Gets packet, source manifest, review state, authorized sender, and export state.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:read
      x-md-scope: packets:read
      parameters:
        - name: packet_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  packet_id:
                    type: string
                  matter_id:
                    type: string
                  type:
                    type: string
                  status:
                    type: string
                  authorized_sender:
                    type: string
                  review_state:
                    type: object
                    properties:
                      review_required:
                        type: boolean
                      review_status:
                        type: string
                      review_owner:
                        type: string
                      review_notes:
                        type: string
                  source_refs:
                    type: array
                    items:
                      type: object
                      properties:
                        source_id:
                          type: string
                        source_type:
                          type: string
                        title:
                          type: string
                        uri:
                          type: string
                        hash:
                          type: string
                        chain_of_custody_id:
                          type: string
                        admissibility_notes:
                          type: string
                  audit:
                    type: object
                    properties:
                      request_id:
                        type: string
                      actor_id:
                        type: string
                      organization_id:
                        type: string
                      matter_id:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
              example:
                packet_id: string
                matter_id: string
                type: string
                status: string
                authorized_sender: string
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
                source_refs:
                  - source_id: ...
                    source_type: ...
                    title: ...
                    uri: ...
                    hash: ...
                    chain_of_custody_id: ...
                    admissibility_notes: ...
                audit:
                  request_id: string
                  actor_id: string
                  organization_id: string
                  matter_id: string
                  timestamp: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/packets/{packet_id}/export:
    post:
      operationId: exportPacket
      summary: Export packet
      description: Exports packet to PDF/ZIP/JSON bundle and records export audit event.
      tags:
        - Packets
      security:
        - protocol_key:
            - packets:export
      x-md-scope: packets:export
      parameters:
        - name: packet_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                redaction_profile:
                  type: string
            example:
              format: pdf
              redaction_profile: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PacketExport"
              example:
                export_id: string
                object_type: string
                object_id: string
                format: pdf
                status: string
                download_url: string
                audit_id: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/issuer-remediation/freeze-packet:
    post:
      operationId: createIssuerFreezePacket
      summary: Create issuer freeze packet
      description: Prepares issuer-controlled freeze/preserve packet for stablecoin issuer workflows.
      tags:
        - Issuer Remediation
      security:
        - protocol_key:
            - issuer:write
      x-md-scope: issuer:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssuerRemediation"
              example:
                remediation_id: string
                matter_id: string
                issuer: string
                asset: string
                network: string
                action_type: freeze_only
                status: string
                destination_wallet_certificate_id: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/issuer-remediation/burn-reissue-packet:
    post:
      operationId: createBurnReissuePacket
      summary: Create burn/reissue packet
      description: Prepares order-backed burn/reissue workflow packet. Micron Delta does not burn, mint, freeze, transfer, or redeem tokens.
      tags:
        - Issuer Remediation
      security:
        - protocol_key:
            - issuer:write
      x-md-scope: issuer:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                judgment_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                packet_type:
                  type: string
                authorized_sender:
                  type: string
                legal_authority_id:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
                notes:
                  type: string
            example:
              matter_id: string
              judgment_id: string
              wallets:
                - string
              packet_type: string
              authorized_sender: string
              legal_authority_id: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
              notes: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssuerRemediation"
              example:
                remediation_id: string
                matter_id: string
                issuer: string
                asset: string
                network: string
                action_type: freeze_only
                status: string
                destination_wallet_certificate_id: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/issuer-remediation/destination-wallet-certificate:
    post:
      operationId: createDestinationWalletCertificate
      summary: Create destination wallet certificate
      description: Creates custody, purpose, chain, signers, sanctions screen, and approval certificate for remittance/reissue destination wallet.
      tags:
        - Issuer Remediation
      security:
        - protocol_key:
            - issuer:write
      x-md-scope: issuer:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallet_address:
                  type: string
                network:
                  type: string
                purpose:
                  type: string
                owner:
                  type: string
                custodian:
                  type: string
                signer_model:
                  type: string
                allowed_assets:
                  type: array
                  items:
                    type: string
            example:
              matter_id: string
              wallet_address: string
              network: string
              purpose: string
              owner: string
              custodian: string
              signer_model: string
              allowed_assets:
                - string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  destination_wallet_id:
                    type: string
                  wallet_address:
                    type: string
                  network:
                    type: string
                  purpose:
                    type: string
                  owner:
                    type: string
                  custodian:
                    type: string
                  sanctions_screen_complete:
                    type: boolean
                  approval_status:
                    type: string
              example:
                destination_wallet_id: string
                wallet_address: string
                network: string
                purpose: string
                owner: string
                custodian: string
                sanctions_screen_complete: true
                approval_status: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/issuer-remediation/{remediation_id}:
    get:
      operationId: getIssuerRemediation
      summary: Get issuer remediation
      description: "Gets issuer remediation status: freeze, burn, reissue, remit, reject, close."
      tags:
        - Issuer Remediation
      security:
        - protocol_key:
            - issuer:read
      x-md-scope: issuer:read
      parameters:
        - name: remediation_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssuerRemediation"
              example:
                remediation_id: string
                matter_id: string
                issuer: string
                asset: string
                network: string
                action_type: freeze_only
                status: string
                destination_wallet_certificate_id: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/sanctions/screen:
    post:
      operationId: runSanctionsScreen
      summary: Run sanctions screen
      description: Screens wallets, entities, addresses, exchanges, and counterparties for SDN/DPRK/Lazarus/TCO/sanctions risk.
      tags:
        - Sanctions
      security:
        - protocol_key:
            - sanctions:screen
      x-md-scope: sanctions:screen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                wallets:
                  type: array
                  items:
                    type: string
                entities:
                  type: array
                  items:
                    type: string
                counterparties:
                  type: array
                  items:
                    type: string
            example:
              matter_id: string
              wallets:
                - string
              entities:
                - string
              counterparties:
                - string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  review_id:
                    type: string
                  status:
                    type: string
                  matches:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  ordinary_collection_paused:
                    type: boolean
                  required_actions:
                    type: array
                    items:
                      type: string
              example:
                review_id: string
                status: clear
                matches:
                  - {}
                ordinary_collection_paused: true
                required_actions:
                  - string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/sanctions/review-packet:
    post:
      operationId: createSanctionsReview
      summary: Create sanctions review packet
      description: Creates sanctions review packet with source manifest, wallet/entity matches, blocked-property issue, and counsel review queue.
      tags:
        - Sanctions
      security:
        - protocol_key:
            - sanctions:write
      x-md-scope: sanctions:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                screen_id:
                  type: string
                notes:
                  type: string
            example:
              matter_id: string
              screen_id: string
              notes: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SanctionsReview"
              example:
                review_id: string
                matter_id: string
                status: string
                blocked_property_analysis: string
                ofac_report_required: true
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/sanctions/ofac-report-workflow:
    post:
      operationId: createOfacReportWorkflow
      summary: Create OFAC report workflow
      description: Creates OFAC reporting/licensing/remittance workflow tracker when sanctions counsel flags potential blocked property.
      tags:
        - Sanctions
      security:
        - protocol_key:
            - sanctions:write
      x-md-scope: sanctions:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                sanctions_review_id:
                  type: string
                report_type:
                  type: string
                counsel_owner:
                  type: string
            example:
              matter_id: string
              sanctions_review_id: string
              report_type: string
              counsel_owner: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ofac_report_id:
                    type: string
                  matter_id:
                    type: string
                  status:
                    type: string
                  submitted_by:
                    type: string
                  submitted_at:
                    type: string
                    format: date-time
              example:
                ofac_report_id: string
                matter_id: string
                status: string
                submitted_by: string
                submitted_at: 2026-06-01T12:00:00Z
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/sanctions/{review_id}:
    get:
      operationId: getSanctionsReview
      summary: Get sanctions review
      description: Gets sanctions review state, matches, required gates, and packet status.
      tags:
        - Sanctions
      security:
        - protocol_key:
            - sanctions:read
      x-md-scope: sanctions:read
      parameters:
        - name: review_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SanctionsReview"
              example:
                review_id: string
                matter_id: string
                status: string
                blocked_property_analysis: string
                ofac_report_required: true
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/watchlists:
    post:
      operationId: createWatchlist
      summary: Create watchlist
      description: Creates matter-tied wallet/token/exchange watchlist.
      tags:
        - Monitoring
      security:
        - protocol_key:
            - monitoring:write
      x-md-scope: monitoring:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                name:
                  type: string
                chains:
                  type: array
                  items:
                    type: string
                thresholds:
                  type: object
                  additionalProperties: true
            example:
              matter_id: string
              name: string
              chains:
                - string
              thresholds: {}
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Watchlist"
              example:
                watchlist_id: string
                matter_id: string
                name: string
                addresses:
                  - string
                status: string
                alert_rules:
                  - {}
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listWatchlists
      summary: List watchlists
      description: Lists matter-tied watchlists.
      tags:
        - Monitoring
      security:
        - protocol_key:
            - monitoring:read
      x-md-scope: monitoring:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        watchlist_id:
                          type: string
                        matter_id:
                          type: string
                        name:
                          type: string
                        addresses:
                          type: string
                        status:
                          type: string
                        alert_rules:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - watchlist_id: ...
                    matter_id: ...
                    name: ...
                    addresses: ...
                    status: ...
                    alert_rules: ...
                has_more: false
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
  /v1/watchlists/{watchlist_id}:
    get:
      operationId: getWatchlist
      summary: Get watchlist
      description: Gets watchlist and alert rules.
      tags:
        - Monitoring
      security:
        - protocol_key:
            - monitoring:read
      x-md-scope: monitoring:read
      parameters:
        - name: watchlist_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Watchlist"
              example:
                watchlist_id: string
                matter_id: string
                name: string
                addresses:
                  - string
                status: string
                alert_rules:
                  - {}
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/watchlists/{watchlist_id}/addresses:
    post:
      operationId: addWatchlistAddresses
      summary: Add watchlist addresses
      description: Adds matter-linked addresses to monitoring watchlist.
      tags:
        - Monitoring
      security:
        - protocol_key:
            - monitoring:write
      x-md-scope: monitoring:write
      parameters:
        - name: watchlist_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                addresses:
                  type: array
                  items:
                    type: string
                reason:
                  type: string
                source_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
            example:
              addresses:
                - string
              reason: string
              source_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Watchlist"
              example:
                watchlist_id: string
                matter_id: string
                name: string
                addresses:
                  - string
                status: string
                alert_rules:
                  - {}
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/alerts:
    get:
      operationId: listAlerts
      summary: List alerts
      description: Lists wallet movement, exchange proximity, stablecoin exposure, sanctions, deadline, and compliance alerts.
      tags:
        - Monitoring
      security:
        - protocol_key:
            - monitoring:read
      x-md-scope: monitoring:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        alert_id:
                          type: string
                        matter_id:
                          type: string
                        type:
                          type: string
                        severity:
                          type: string
                        status:
                          type: string
                        target:
                          type: string
                        reason:
                          type: string
                        created_at:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - alert_id: ...
                    matter_id: ...
                    type: ...
                    severity: ...
                    status: ...
                    target: ...
                    reason: ...
                    created_at: ...
                has_more: false
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
  /v1/alerts/{alert_id}/triage:
    post:
      operationId: triageAlert
      summary: Triage alert
      description: Marks alert actionability, creates linked actions/packets, or closes false positive.
      tags:
        - Monitoring
      security:
        - protocol_key:
            - monitoring:write
      x-md-scope: monitoring:write
      parameters:
        - name: alert_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                notes:
                  type: string
                create_action:
                  type: boolean
                create_packet_type:
                  type: string
            example:
              status: actionable
              notes: string
              create_action: true
              create_packet_type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  alert_id:
                    type: string
                  matter_id:
                    type: string
                  type:
                    type: string
                  severity:
                    type: string
                  status:
                    type: string
                  target:
                    type: string
                  reason:
                    type: string
                  created_at:
                    type: string
                    format: date-time
              example:
                alert_id: string
                matter_id: string
                type: string
                severity: string
                status: string
                target: string
                reason: string
                created_at: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/actions:
    post:
      operationId: createAction
      summary: Create action
      description: Creates operator/counsel/vendor/review action.
      tags:
        - Actions
      security:
        - protocol_key:
            - actions:write
      x-md-scope: actions:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                type:
                  type: string
                title:
                  type: string
                campaign_id:
                  type: string
                owner_id:
                  type: string
                priority:
                  type: string
                due_at:
                  type: string
                  format: date-time
                linked_packet_id:
                  type: string
            example:
              matter_id: string
              type: string
              title: string
              campaign_id: string
              owner_id: string
              priority: string
              due_at: 2026-06-01T12:00:00Z
              linked_packet_id: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                action_id: string
                matter_id: string
                campaign_id: string
                type: string
                title: string
                owner_id: string
                priority: string
                status: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: listActions
      summary: List actions
      description: Lists actions filtered by owner, matter, campaign, status, and due date.
      tags:
        - Actions
      security:
        - protocol_key:
            - actions:read
      x-md-scope: actions:read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionList"
              example:
                object: list
                data:
                  - action_id: ...
                    matter_id: ...
                    campaign_id: ...
                    type: ...
                    title: ...
                    owner_id: ...
                    priority: ...
                    status: ...
                has_more: false
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
  /v1/actions/{action_id}:
    get:
      operationId: getAction
      summary: Get action
      description: Gets action details, requirements, status, and linked packet/evidence.
      tags:
        - Actions
      security:
        - protocol_key:
            - actions:read
      x-md-scope: actions:read
      parameters:
        - name: action_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                action_id: string
                matter_id: string
                campaign_id: string
                type: string
                title: string
                owner_id: string
                priority: string
                status: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: updateAction
      summary: Update action
      description: Updates status, owner, priority, due date, and evidence requirements.
      tags:
        - Actions
      security:
        - protocol_key:
            - actions:write
      x-md-scope: actions:write
      parameters:
        - name: action_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                status:
                  type: string
                priority:
                  type: string
                owner_id:
                  type: string
                due_at:
                  type: string
                  format: date-time
            example:
              title: string
              status: string
              priority: string
              owner_id: string
              due_at: 2026-06-01T12:00:00Z
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                action_id: string
                matter_id: string
                campaign_id: string
                type: string
                title: string
                owner_id: string
                priority: string
                status: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/actions/{action_id}/assign:
    post:
      operationId: assignAction
      summary: Assign action
      description: Assigns action to operator, counsel, analyst, vendor, or reviewer.
      tags:
        - Actions
      security:
        - protocol_key:
            - actions:assign
      x-md-scope: actions:assign
      parameters:
        - name: action_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                owner_id:
                  type: string
                notes:
                  type: string
            example:
              owner_id: string
              notes: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                action_id: string
                matter_id: string
                campaign_id: string
                type: string
                title: string
                owner_id: string
                priority: string
                status: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/actions/{action_id}/complete:
    post:
      operationId: completeAction
      summary: Complete action
      description: Completes action with completion evidence and audit event.
      tags:
        - Actions
      security:
        - protocol_key:
            - actions:complete
      x-md-scope: actions:complete
      parameters:
        - name: action_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                completion_notes:
                  type: string
                evidence_refs:
                  type: array
                  items:
                    type: object
                    properties:
                      source_id:
                        type: string
                      source_type:
                        type: string
                      title:
                        type: string
                      uri:
                        type: string
                      hash:
                        type: string
                      chain_of_custody_id:
                        type: string
                      admissibility_notes:
                        type: string
            example:
              completion_notes: string
              evidence_refs:
                - source_id: ...
                  source_type: ...
                  title: ...
                  uri: ...
                  hash: ...
                  chain_of_custody_id: ...
                  admissibility_notes: ...
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
              example:
                action_id: string
                matter_id: string
                campaign_id: string
                type: string
                title: string
                owner_id: string
                priority: string
                status: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/actions/matters/{matter_id}:
    get:
      operationId: listMatterActions
      summary: List matter actions
      description: Lists actions for a matter.
      tags:
        - Actions
      security:
        - protocol_key:
            - actions:read
      x-md-scope: actions:read
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionList"
              example:
                object: list
                data:
                  - action_id: ...
                    matter_id: ...
                    campaign_id: ...
                    type: ...
                    title: ...
                    owner_id: ...
                    priority: ...
                    status: ...
                has_more: false
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/ledger/recovery-events:
    post:
      operationId: createRecoveryEvent
      summary: Create recovery event
      description: Records frozen, blocked, seized, turned over, remitted, settled, or recovered value.
      tags:
        - Ledger
      security:
        - protocol_key:
            - ledger:write
      x-md-scope: ledger:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                event_type:
                  type: string
                asset:
                  type: string
                gross_amount:
                  type: number
                network:
                  type: string
                usd_value:
                  type: number
                source:
                  type: string
                packet_id:
                  type: string
            example:
              matter_id: string
              event_type: frozen
              asset: string
              gross_amount: 123.45
              network: string
              usd_value: 123.45
              source: string
              packet_id: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  recovery_event_id:
                    type: string
                  matter_id:
                    type: string
                  event_type:
                    type: string
                  asset:
                    type: string
                  gross_amount:
                    type: number
                  status:
                    type: string
                  audit:
                    type: object
                    properties:
                      request_id:
                        type: string
                      actor_id:
                        type: string
                      organization_id:
                        type: string
                      matter_id:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
              example:
                recovery_event_id: string
                matter_id: string
                event_type: string
                asset: string
                gross_amount: 123.45
                status: string
                audit:
                  request_id: string
                  actor_id: string
                  organization_id: string
                  matter_id: string
                  timestamp: 2026-06-01T12:00:00Z
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/ledger/remittance-events:
    post:
      operationId: createRemittanceEvent
      summary: Create remittance event
      description: Records remittance to receiver, court registry, custodian, claimant, or waterfall account.
      tags:
        - Ledger
      security:
        - protocol_key:
            - ledger:write
      x-md-scope: ledger:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                destination:
                  type: string
                amount:
                  type: number
                asset:
                  type: string
                waterfall_id:
                  type: string
                source_recovery_event_id:
                  type: string
            example:
              matter_id: string
              destination: string
              amount: 123.45
              asset: string
              waterfall_id: string
              source_recovery_event_id: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  remittance_event_id:
                    type: string
                  matter_id:
                    type: string
                  destination:
                    type: string
                  asset:
                    type: string
                  amount:
                    type: number
                  status:
                    type: string
                  audit:
                    type: object
                    properties:
                      request_id:
                        type: string
                      actor_id:
                        type: string
                      organization_id:
                        type: string
                      matter_id:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
              example:
                remittance_event_id: string
                matter_id: string
                destination: string
                asset: string
                amount: 123.45
                status: string
                audit:
                  request_id: string
                  actor_id: string
                  organization_id: string
                  matter_id: string
                  timestamp: 2026-06-01T12:00:00Z
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/ledger/matters/{matter_id}:
    get:
      operationId: getMatterLedger
      summary: Get matter ledger
      description: Gets recovery/remittance/collection ledger for a matter.
      tags:
        - Ledger
      security:
        - protocol_key:
            - ledger:read
      x-md-scope: ledger:read
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  matter_id:
                    type: string
                  recovery_events:
                    type: array
                    items:
                      type: object
                      properties:
                        recovery_event_id:
                          type: string
                        matter_id:
                          type: string
                        event_type:
                          type: string
                        asset:
                          type: string
                        gross_amount:
                          type: string
                        status:
                          type: string
                        audit:
                          type: string
                  remittance_events:
                    type: array
                    items:
                      type: object
                      properties:
                        remittance_event_id:
                          type: string
                        matter_id:
                          type: string
                        destination:
                          type: string
                        asset:
                          type: string
                        amount:
                          type: string
                        status:
                          type: string
                        audit:
                          type: string
                  total_recovered:
                    $ref: "#/components/schemas/Money"
              example:
                matter_id: string
                recovery_events:
                  - recovery_event_id: ...
                    matter_id: ...
                    event_type: ...
                    asset: ...
                    gross_amount: ...
                    status: ...
                    audit: ...
                remittance_events:
                  - remittance_event_id: ...
                    matter_id: ...
                    destination: ...
                    asset: ...
                    amount: ...
                    status: ...
                    audit: ...
                total_recovered:
                  amount: 123.45
                  currency: string
                  valuation_time: 2026-06-01T12:00:00Z
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/waterfall/calculate:
    post:
      operationId: calculateWaterfall
      summary: Calculate waterfall
      description: Calculates costs, counsel fees, Meridian economics, claimant distributions, holdbacks, and remittance constraints.
      tags:
        - Ledger
      security:
        - protocol_key:
            - waterfall:calculate
      x-md-scope: waterfall:calculate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                recovery_event_ids:
                  type: array
                  items:
                    type: string
                costs:
                  type: object
                  additionalProperties: true
                meridian_percentage:
                  type: number
            example:
              matter_id: string
              recovery_event_ids:
                - string
              costs: {}
              meridian_percentage: 123.45
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Waterfall"
              example:
                waterfall_id: string
                matter_id: string
                gross_recovered:
                  amount: 123.45
                  currency: string
                  valuation_time: 2026-06-01T12:00:00Z
                costs: {}
                meridian_economics:
                  amount: 123.45
                  currency: string
                  valuation_time: 2026-06-01T12:00:00Z
                claimant_distributions:
                  - claimant_id: string
                    amount: 123.45
                holdbacks:
                  - {}
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/waterfall/matters/{matter_id}:
    get:
      operationId: getMatterWaterfall
      summary: Get matter waterfall
      description: Gets current matter economics and distribution waterfall.
      tags:
        - Ledger
      security:
        - protocol_key:
            - waterfall:read
      x-md-scope: waterfall:read
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Waterfall"
              example:
                waterfall_id: string
                matter_id: string
                gross_recovered:
                  amount: 123.45
                  currency: string
                  valuation_time: 2026-06-01T12:00:00Z
                costs: {}
                meridian_economics:
                  amount: 123.45
                  currency: string
                  valuation_time: 2026-06-01T12:00:00Z
                claimant_distributions:
                  - claimant_id: string
                    amount: 123.45
                holdbacks:
                  - {}
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/reports/campaign-brief:
    post:
      operationId: generateCampaignBrief
      summary: Generate campaign brief
      description: Generates executive/counsel/operator campaign brief with board metrics, risks, next actions, and source-linked attachments.
      tags:
        - Reports
      security:
        - protocol_key:
            - reports:write
      x-md-scope: reports:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                audience:
                  type: string
                include_sections:
                  type: array
                  items:
                    type: string
            example:
              matter_id: string
              audience: internal
              include_sections:
                - string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Report"
              example:
                report_id: string
                matter_id: string
                type: string
                status: string
                content_uri: string
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/reports/claimant-update:
    post:
      operationId: generateClaimantUpdate
      summary: Generate claimant update
      description: Generates claimant-facing update with sanitized status, recovery events, and next milestones.
      tags:
        - Reports
      security:
        - protocol_key:
            - reports:write
      x-md-scope: reports:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                claimant_id:
                  type: string
                redaction_profile:
                  type: string
            example:
              matter_id: string
              claimant_id: string
              redaction_profile: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Report"
              example:
                report_id: string
                matter_id: string
                type: string
                status: string
                content_uri: string
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/reports/{report_id}:
    get:
      operationId: getReport
      summary: Get report
      description: Gets report metadata and content pointers.
      tags:
        - Reports
      security:
        - protocol_key:
            - reports:read
      x-md-scope: reports:read
      parameters:
        - name: report_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Report"
              example:
                report_id: string
                matter_id: string
                type: string
                status: string
                content_uri: string
                review_state:
                  review_required: true
                  review_status: not_required
                  review_owner: string
                  review_notes: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/reports/{report_id}/export:
    post:
      operationId: exportReport
      summary: Export report
      description: Exports report to PDF/ZIP/JSON and writes audit event.
      tags:
        - Reports
      security:
        - protocol_key:
            - reports:export
      x-md-scope: reports:export
      parameters:
        - name: report_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                redaction_profile:
                  type: string
            example:
              format: pdf
              redaction_profile: string
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PacketExport"
              example:
                export_id: string
                object_type: string
                object_id: string
                format: pdf
                status: string
                download_url: string
                audit_id: string
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/audit/matters/{matter_id}:
    get:
      operationId: getMatterAudit
      summary: Get matter audit
      description: Gets audit events for a matter with filters by object, actor, event type, export state, and time range.
      tags:
        - Audit
      security:
        - protocol_key:
            - audit:read
      x-md-scope: audit:read
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        event_id:
                          type: string
                        matter_id:
                          type: string
                        event_type:
                          type: string
                        actor_id:
                          type: string
                        object_type:
                          type: string
                        object_id:
                          type: string
                        timestamp:
                          type: string
                        details:
                          type: string
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
              example:
                object: list
                data:
                  - event_id: ...
                    matter_id: ...
                    event_type: ...
                    actor_id: ...
                    object_type: ...
                    object_id: ...
                    timestamp: ...
                    details: ...
                has_more: false
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/audit/events:
    post:
      operationId: createAuditEvent
      summary: Create audit event
      description: Creates a custom audit event for external actions or manual events.
      tags:
        - Audit
      security:
        - protocol_key:
            - audit:write
      x-md-scope: audit:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                matter_id:
                  type: string
                event_type:
                  type: string
                object_type:
                  type: string
                object_id:
                  type: string
                details:
                  type: object
                  additionalProperties: true
            example:
              matter_id: string
              event_type: string
              object_type: string
              object_id: string
              details: {}
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditEvent"
              example:
                event_id: string
                matter_id: string
                event_type: string
                actor_id: string
                object_type: string
                object_id: string
                timestamp: 2026-06-01T12:00:00Z
                details: {}
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/audit/events/{event_id}:
    get:
      operationId: getAuditEvent
      summary: Get audit event
      description: Gets a single audit event.
      tags:
        - Audit
      security:
        - protocol_key:
            - audit:read
      x-md-scope: audit:read
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditEvent"
              example:
                event_id: string
                matter_id: string
                event_type: string
                actor_id: string
                object_type: string
                object_id: string
                timestamp: 2026-06-01T12:00:00Z
                details: {}
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Error envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/webhook_endpoints:
    post:
      tags:
        - Webhook Endpoints
      summary: Create a webhook endpoint
      operationId: createWebhookEndpoint
      description: Registers an HTTPS endpoint for signed event deliveries. The signing_secret is returned once, on this response only — store it; you need it to verify MD-Signature headers.
      x-md-scope: webhook_endpoints:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  description: HTTPS URL that receives event POSTs.
                enabled_events:
                  type: array
                  items:
                    type: string
                  description: Event types to deliver. Omit (or pass ["*"]) for all events.
            example:
              url: https://example.com/md/webhooks
              enabled_events:
                - judgment.created
                - packet.created
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_endpoint_id:
                    type: string
                  url:
                    type: string
                  enabled_events:
                    type: array
                    items:
                      type: string
                    description: Event types this endpoint receives. ["*"] subscribes to everything.
                  status:
                    type: string
                    enum:
                      - enabled
                      - disabled
                  created_at:
                    type: string
                    format: date-time
                  signing_secret:
                    type: string
                    description: Returned once. Verify MD-Signature with this.
    get:
      tags:
        - Webhook Endpoints
      summary: List webhook endpoints
      operationId: listWebhookEndpoints
      x-md-scope: webhook_endpoints:read
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size, 1–100. Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: starting_after
          in: query
          required: false
          description: "Cursor: the id of the last item on the page you have. Returns the page after it."
          schema:
            type: string
        - name: ending_before
          in: query
          required: false
          description: "Cursor: the id of the first item on the page you have. Returns the page before it."
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
                properties:
                  object:
                    type: string
                    enum:
                      - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        webhook_endpoint_id:
                          type: string
                        url:
                          type: string
                        enabled_events:
                          type: array
                          items:
                            type: string
                          description: Event types this endpoint receives. ["*"] subscribes to everything.
                        status:
                          type: string
                          enum:
                            - enabled
                            - disabled
                        created_at:
                          type: string
                          format: date-time
                  has_more:
                    type: boolean
                required:
                  - object
                  - data
                  - has_more
  /v1/webhook_endpoints/{webhook_endpoint_id}:
    get:
      tags:
        - Webhook Endpoints
      summary: Retrieve a webhook endpoint
      operationId: getWebhookEndpoint
      x-md-scope: webhook_endpoints:read
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      tags:
        - Webhook Endpoints
      summary: Update a webhook endpoint
      operationId: updateWebhookEndpoint
      description: Update the URL, event filter, or status. Disabled endpoints stop receiving deliveries immediately.
      x-md-scope: webhook_endpoints:write
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                enabled_events:
                  type: array
                  items:
                    type: string
                status:
                  type: string
                  enum:
                    - enabled
                    - disabled
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - Webhook Endpoints
      summary: Delete a webhook endpoint
      operationId: deleteWebhookEndpoint
      x-md-scope: webhook_endpoints:write
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_endpoint_id:
                    type: string
                  deleted:
                    type: boolean
        "404":
          description: Not found — no resource with this id exists in your organization and environment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
webhooks:
  judgment.validated:
    post:
      summary: judgment.validated
      description: A judgment passed the full readiness battery.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  matter.authority.granted:
    post:
      summary: matter.authority.granted
      description: An authority model was granted on a matter.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  debtor.graph.updated:
    post:
      summary: debtor.graph.updated
      description: "The adversary graph changed: node or edge added, merged, or rescored."
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  campaign.action.assigned:
    post:
      summary: campaign.action.assigned
      description: A claw campaign assigned an action to an operator queue.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  alert.movement.detected:
    post:
      summary: alert.movement.detected
      description: Monitoring detected asset movement on a watched target.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  attribution.claim.scored:
    post:
      summary: attribution.claim.scored
      description: An attribution claim received a confidence score.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  packet.exchange_freeze.exported:
    post:
      summary: packet.exchange_freeze.exported
      description: An exchange-freeze packet was exported for service.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  sanctions.screen.hit:
    post:
      summary: sanctions.screen.hit
      description: A sanctions screen returned a hit; the gate is now active.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  ledger.recovery_event.recorded:
    post:
      summary: ledger.recovery_event.recorded
      description: A recovery event was recorded to the ledger.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  waterfall.calculated:
    post:
      summary: waterfall.calculated
      description: A distribution waterfall was calculated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  matter.created:
    post:
      summary: matter.created
      description: A matter was opened.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  matter.closed:
    post:
      summary: matter.closed
      description: A matter was closed (paid, settled, exhausted, stayed, or administrative).
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  matter.authority.revoked:
    post:
      summary: matter.authority.revoked
      description: An authority grant was revoked or expired.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  judgment.created:
    post:
      summary: judgment.created
      description: A judgment record was created from intake. (Renamed from judgment.intaken; the old name is accepted as an enabled_events alias under 2026-06-11 and will be removed in the next date version.)
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  judgment.validation_failed:
    post:
      summary: judgment.validation_failed
      description: A judgment failed readiness; failing gates are named in the payload.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  judgment.deadline.approaching:
    post:
      summary: judgment.deadline.approaching
      description: A judgment deadline enters its warning window.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  claimant.added:
    post:
      summary: claimant.added
      description: A claimant was added to a matter.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  claimant.verified:
    post:
      summary: claimant.verified
      description: A claimant completed verification.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  debtor.added:
    post:
      summary: debtor.added
      description: A debtor entity was added to the adversary graph.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  relationship.asserted:
    post:
      summary: relationship.asserted
      description: A relationship edge was asserted between graph entities.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  attribution.claim.created:
    post:
      summary: attribution.claim.created
      description: An attribution claim was created (pre-scoring).
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  attribution.network.updated:
    post:
      summary: attribution.network.updated
      description: Network attribution recomputed cluster membership.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  crypto.trace.completed:
    post:
      summary: crypto.trace.completed
      description: A crypto trace run completed.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  crypto.exposure.updated:
    post:
      summary: crypto.exposure.updated
      description: Exchange exposure for a traced wallet changed.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  campaign.created:
    post:
      summary: campaign.created
      description: A claw campaign was created.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  campaign.completed:
    post:
      summary: campaign.completed
      description: A claw campaign reached a terminal state.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  packet.created:
    post:
      summary: packet.created
      description: An enforcement packet was assembled.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  packet.turnover.exported:
    post:
      summary: packet.turnover.exported
      description: A turnover packet was exported for service.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  remediation.case.opened:
    post:
      summary: remediation.case.opened
      description: An issuer remediation case was opened.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  remediation.case.resolved:
    post:
      summary: remediation.case.resolved
      description: An issuer remediation case was resolved.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  sanctions.screen.cleared:
    post:
      summary: sanctions.screen.cleared
      description: A prior sanctions hit was reviewed and cleared; the gate lifts.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.
  report.generated:
    post:
      summary: report.generated
      description: A requested report finished generating.
      x-md-status: proposed
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"
      responses:
        "200":
          description: Acknowledge with any 2xx within 10s.

  # ── v2 Roadmap endpoints (coming soon) ─────────────────────

  /v2/documents:
    post:
      operationId: uploadDocument
      summary: "[Planned] Upload document"
      description: Upload a file and attach it to a matter. Supports PDF, DOCX, PNG, JPG. Max 50MB. Chain-of-custody metadata recorded on upload.
      tags: [Documents]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.
    get:
      operationId: listDocuments
      summary: "[Planned] List documents"
      description: List documents for a matter, filterable by station, tag, and upload date.
      tags: [Documents]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/documents/{document_id}:
    get:
      operationId: getDocument
      summary: "[Planned] Get document"
      description: Retrieve document metadata and a signed download URL.
      tags: [Documents]
      x-md-status: planned
      parameters:
        - name: document_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.
    delete:
      operationId: deleteDocument
      summary: "[Planned] Delete document"
      description: Soft-delete a document. Audit trail preserved.
      tags: [Documents]
      x-md-status: planned
      parameters:
        - name: document_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/documents/{document_id}/chain-of-custody:
    get:
      operationId: getDocumentChainOfCustody
      summary: "[Planned] Get document chain of custody"
      description: Full chain-of-custody log for a document. Every access, download, and share is recorded.
      tags: [Documents]
      x-md-status: planned
      parameters:
        - name: document_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/filings:
    post:
      operationId: generateFiling
      summary: "[Planned] Generate court filing"
      description: Generate a court filing from matter data. Supports discovery orders, turnover motions, contempt motions, and receiver reports. Output as PDF.
      tags: [Filings]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.
    get:
      operationId: listFilings
      summary: "[Planned] List filings"
      description: List generated filings for a matter.
      tags: [Filings]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/filings/{filing_id}:
    get:
      operationId: getFiling
      summary: "[Planned] Get filing"
      description: Retrieve a generated filing with metadata and download link.
      tags: [Filings]
      x-md-status: planned
      parameters:
        - name: filing_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/filings/{filing_id}/export:
    post:
      operationId: exportFiling
      summary: "[Planned] Export filing as PDF"
      description: Render the filing to a court-ready PDF with exhibits attached.
      tags: [Filings]
      x-md-status: planned
      parameters:
        - name: filing_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/filings/templates:
    get:
      operationId: listFilingTemplates
      summary: "[Planned] List filing templates"
      description: List available filing templates by jurisdiction and filing type.
      tags: [Filings]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/fees:
    post:
      operationId: recordFee
      summary: "[Planned] Record fee or cost"
      description: Record an attorney fee, receiver fee, expert cost, or other expense against a matter. Links to Ledger.
      tags: [Fees]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.
    get:
      operationId: listFees
      summary: "[Planned] List fees and costs"
      description: List all fees and costs for a matter, grouped by category.
      tags: [Fees]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/fees/matters/{matter_id}/accounting:
    get:
      operationId: getMatterAccounting
      summary: "[Planned] Get matter accounting"
      description: Full accounting for a matter. Recovery, fees, costs, net distribution. Court-ready format.
      tags: [Fees]
      x-md-status: planned
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/batch/debtors:
    post:
      operationId: batchImportDebtors
      summary: "[Planned] Batch import debtors"
      description: Import up to 500 debtors in a single request. Returns a batch job ID for status polling.
      tags: [Batch]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/batch/sanctions-screen:
    post:
      operationId: batchSanctionsScreen
      summary: "[Planned] Batch sanctions screening"
      description: Screen up to 200 entities against OFAC/SDN and global sanctions lists in a single request.
      tags: [Batch]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/batch/wallets:
    post:
      operationId: batchImportWallets
      summary: "[Planned] Batch import wallets"
      description: Import up to 1000 wallet addresses for attribution analysis. Returns a batch job ID.
      tags: [Batch]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/batch/{batch_id}:
    get:
      operationId: getBatchStatus
      summary: "[Planned] Get batch job status"
      description: Poll the status of a batch import or screening job.
      tags: [Batch]
      x-md-status: planned
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/deadlines:
    post:
      operationId: createDeadline
      summary: "[Planned] Create deadline"
      description: Create a deadline for a matter. Statute of limitations, filing deadlines, response windows, hearing dates.
      tags: [Deadlines]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.
    get:
      operationId: listDeadlines
      summary: "[Planned] List deadlines"
      description: List upcoming deadlines across matters. Filterable by urgency, type, and jurisdiction.
      tags: [Deadlines]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/deadlines/{deadline_id}:
    get:
      operationId: getDeadline
      summary: "[Planned] Get deadline"
      description: Retrieve deadline details including alert schedule and linked matter.
      tags: [Deadlines]
      x-md-status: planned
      parameters:
        - name: deadline_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.
    patch:
      operationId: updateDeadline
      summary: "[Planned] Update deadline"
      description: Update a deadline (extend, resolve, or reschedule).
      tags: [Deadlines]
      x-md-status: planned
      parameters:
        - name: deadline_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/jurisdictions:
    get:
      operationId: listJurisdictions
      summary: "[Planned] List supported jurisdictions"
      description: List jurisdictions with supported enforcement paths, domestication requirements, and service rules.
      tags: [Jurisdictions]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/jurisdictions/{jurisdiction_id}/enforcement-paths:
    get:
      operationId: getEnforcementPaths
      summary: "[Planned] Get enforcement paths for jurisdiction"
      description: Available enforcement paths for a jurisdiction. Domestication, garnishment, turnover, contempt, asset freeze.
      tags: [Jurisdictions]
      x-md-status: planned
      parameters:
        - name: jurisdiction_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/jurisdictions/domestication:
    post:
      operationId: createDomesticationRequest
      summary: "[Planned] Create domestication request"
      description: Track domestication of a foreign judgment into a target jurisdiction. Generates required filings.
      tags: [Jurisdictions]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/collaboration/invitations:
    post:
      operationId: createCollaborationInvitation
      summary: "[Planned] Invite collaborator"
      description: Invite another party to a matter with scoped permissions. Receiver invites counsel, counsel invites co-counsel.
      tags: [Collaboration]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.
    get:
      operationId: listCollaborationInvitations
      summary: "[Planned] List collaboration invitations"
      description: List pending and accepted collaboration invitations for a matter.
      tags: [Collaboration]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/collaboration/matters/{matter_id}/access:
    get:
      operationId: getMatterAccessList
      summary: "[Planned] Get matter access list"
      description: List all parties with access to a matter, their roles, and permission scopes.
      tags: [Collaboration]
      x-md-status: planned
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/collaboration/matters/{matter_id}/access/{access_id}:
    patch:
      operationId: updateMatterAccess
      summary: "[Planned] Update collaborator access"
      description: Update a collaborator's permission scope on a matter.
      tags: [Collaboration]
      x-md-status: planned
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
        - name: access_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.
    delete:
      operationId: revokeCollaboratorAccess
      summary: "[Planned] Revoke collaborator access"
      description: Revoke a collaborator's access to a matter. Audit event recorded.
      tags: [Collaboration]
      x-md-status: planned
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
        - name: access_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not yet implemented.

  /v2/insurance/bonds:
    post:
      operationId: recordBond
      summary: "[Planned] Record receiver bond"
      description: Record a receiver bond with surety, amount, and court order reference.
      tags: [Insurance]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.
    get:
      operationId: listBonds
      summary: "[Planned] List bonds"
      description: List all active bonds and insurance policies.
      tags: [Insurance]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

  /v2/insurance/policies:
    post:
      operationId: recordInsurancePolicy
      summary: "[Planned] Record insurance policy"
      description: Record fidelity insurance, E&O, or other coverage. Link to matters and receiver appointments.
      tags: [Insurance]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.
    get:
      operationId: listInsurancePolicies
      summary: "[Planned] List insurance policies"
      description: List all insurance policies with coverage details and expiration alerts.
      tags: [Insurance]
      x-md-status: planned
      responses:
        "501":
          description: Not yet implemented.

components:
  securitySchemes:
    protocol_key:
      type: oauth2
      description: "Scoped protocol keys (md_live_ / md_test_). Send as Authorization: Bearer."
      flows:
        clientCredentials:
          tokenUrl: https://api.microndelta.com/v1/oauth/token
          scopes:
            actions:assign: actions — assign
            actions:complete: actions — complete
            actions:read: actions — read
            actions:write: actions — write
            attribution:graph: attribution — graph
            attribution:read: attribution — read
            attribution:score: attribution — score
            attribution:write: attribution — write
            audit:read: audit — read
            audit:write: audit — write
            capabilities:read: capabilities — read
            claimants:read: claimants — read
            claimants:write: claimants — write
            claw:operate: claw — operate
            claw:pressure: claw — pressure
            claw:read: claw — read
            claw:write: claw — write
            crypto:exchange: crypto — exchange
            crypto:map: crypto — map
            crypto:read: crypto — read
            crypto:stablecoin: crypto — stablecoin
            crypto:timeline: crypto — timeline
            debtors:graph: debtors — graph
            debtors:read: debtors — read
            debtors:write: debtors — write
            health:read: health — read
            issuer:read: issuer — read
            issuer:write: issuer — write
            judgments:plan: judgments — plan
            judgments:read: judgments — read
            judgments:validate: judgments — validate
            judgments:write: judgments — write
            keys:read: keys — read
            keys:write: keys — write
            ledger:read: ledger — read
            ledger:write: ledger — write
            matters:read: matters — read
            matters:write: matters — write
            monitoring:read: monitoring — read
            monitoring:write: monitoring — write
            network:correlate: network — correlate
            network:read: network — read
            network:write: network — write
            org:read: org — read
            org:write: org — write
            packets:export: packets — export
            packets:read: packets — read
            packets:write: packets — write
            relationships:read: relationships — read
            relationships:write: relationships — write
            reports:export: reports — export
            reports:read: reports — read
            reports:write: reports — write
            sanctions:read: sanctions — read
            sanctions:screen: sanctions — screen
            sanctions:write: sanctions — write
            users:read: users — read
            users:write: users — write
            waterfall:calculate: waterfall — calculate
            waterfall:read: waterfall — read
            webhook_endpoints:read: List and retrieve webhook endpoints.
            webhook_endpoints:write: Create, update, and delete webhook endpoints.
  schemas:
    Money:
      type: object
      description: Monetary amount with valuation timestamp.
      properties:
        amount:
          type: number
        currency:
          type: string
        valuation_time:
          type: string
          format: date-time
      required:
        - amount
        - currency
    Error:
      type: object
      description: Uniform error envelope. Eight transport codes, three domain gates (authority_required, sanctions_gate, stay_in_effect) — the gates are the contract and never soft-pass.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_request
                - unauthenticated
                - insufficient_scope
                - not_found
                - conflict
                - rate_limited
                - quota_exceeded
                - internal_error
                - authority_required
                - sanctions_gate
                - stay_in_effect
            message:
              type: string
            md_request_id:
              type: string
    Event:
      type: object
      description: Webhook event envelope. HMAC-SHA256 signed (MD-Signature header).
      properties:
        id:
          type: string
        type:
          type: string
        created:
          type: string
          format: date-time
        livemode:
          type: boolean
        data:
          type: object
          additionalProperties: true
      required:
        - id
        - type
        - created
        - data
    Organization:
      type: object
      properties:
        organization_id:
          type: string
        name:
          type: string
        type:
          type: string
        created_at:
          type: string
          format: date-time
        features:
          type: array
          items:
            type: string
    Matter:
      type: object
      properties:
        matter_id:
          type: string
        name:
          type: string
        mode:
          type: string
        status:
          type: string
        organization_id:
          type: string
        lead_counsel:
          type: string
        economics:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    Judgment:
      type: object
      properties:
        judgment_id:
          type: string
        matter_id:
          type: string
        court:
          type: string
        case_number:
          type: string
        jurisdiction:
          type: string
        date_entered:
          type: string
          format: date
        creditor:
          type: string
        debtor:
          type: string
    Claimant:
      type: object
      properties:
        claimant_id:
          type: string
        matter_id:
          type: string
        name:
          type: string
        role:
          type: string
        economics:
          type: object
          additionalProperties: true
        review_state:
          type: object
          properties:
            review_required:
              type: boolean
            review_status:
              type: string
            review_owner:
              type: string
            review_notes:
              type: string
    Debtor:
      type: object
      properties:
        debtor_id:
          type: string
        matter_id:
          type: string
        type:
          type: string
        legal_name:
          type: string
        aliases:
          type: array
          items:
            type: string
        identifiers:
          type: object
          additionalProperties: true
        wallets:
          type: array
          items:
            type: string
        review_state:
          type: object
          properties:
            review_required:
              type: boolean
            review_status:
              type: string
            review_owner:
              type: string
            review_notes:
              type: string
    Relationship:
      type: object
      properties:
        relationship_id:
          type: string
        counterparty_type:
          type: string
        counterparty_name:
          type: string
        channel_type:
          type: string
        usable_by_meridian:
          type: boolean
        usable_by_counsel:
          type: boolean
        usable_by_law_enforcement:
          type: boolean
        authorized_submitter_required:
          type: boolean
    ClawCampaign:
      type: object
      properties:
        campaign_id:
          type: string
        matter_id:
          type: string
        judgment_id:
          type: string
        mode:
          type: string
        pressure_level:
          type: integer
        target_set:
          type: object
          additionalProperties: true
        operator_state:
          type: object
          properties:
            focus_score:
              type: number
            expand_queue:
              type: integer
            next_claw_action:
              type: string
        gates:
          type: array
          items:
            type: object
            properties:
              gate:
                type: string
              status:
                type: string
              reasons:
                type: string
              required_actions:
                type: string
    Action:
      type: object
      properties:
        action_id:
          type: string
        matter_id:
          type: string
        campaign_id:
          type: string
        type:
          type: string
        title:
          type: string
        owner_id:
          type: string
        priority:
          type: string
        status:
          type: string
    Report:
      type: object
      properties:
        report_id:
          type: string
        matter_id:
          type: string
        type:
          type: string
        status:
          type: string
        content_uri:
          type: string
        review_state:
          type: object
          properties:
            review_required:
              type: boolean
            review_status:
              type: string
            review_owner:
              type: string
            review_notes:
              type: string
    WebhookEndpoint:
      type: object
      properties:
        webhook_endpoint_id:
          type: string
        url:
          type: string
        enabled_events:
          type: array
          items:
            type: string
          description: Event types this endpoint receives. ["*"] subscribes to everything.
        status:
          type: string
          enum:
            - enabled
            - disabled
        created_at:
          type: string
          format: date-time
    Waterfall:
      type: object
      properties:
        waterfall_id:
          type: string
        matter_id:
          type: string
        gross_recovered:
          $ref: "#/components/schemas/Money"
        costs:
          type: object
          additionalProperties: true
        meridian_economics:
          $ref: "#/components/schemas/Money"
        claimant_distributions:
          type: array
          items:
            type: object
            properties:
              claimant_id:
                type: string
              amount:
                type: number
        holdbacks:
          type: array
          items:
            type: object
            additionalProperties: true
        review_state:
          type: object
          properties:
            review_required:
              type: boolean
            review_status:
              type: string
            review_owner:
              type: string
            review_notes:
              type: string
    Watchlist:
      type: object
      properties:
        watchlist_id:
          type: string
        matter_id:
          type: string
        name:
          type: string
        addresses:
          type: array
          items:
            type: string
        status:
          type: string
        alert_rules:
          type: array
          items:
            type: object
            additionalProperties: true
    AttributionGraph:
      type: object
      properties:
        graph_id:
          type: string
        matter_id:
          type: string
        nodes:
          type: array
          items:
            type: object
            additionalProperties: true
        edges:
          type: array
          items:
            type: object
            additionalProperties: true
        claims:
          type: array
          items:
            type: object
            properties:
              claim_id:
                type: string
              matter_id:
                type: string
              subject:
                type: string
              predicate:
                type: string
              object:
                type: string
              source_type:
                type: string
              source_refs:
                type: string
              confidence:
                type: string
        confidence_matrix:
          type: array
          items:
            type: object
            properties:
              claim_id:
                type: string
              score:
                type: string
              label:
                type: string
              basis:
                type: string
    CryptoAssetMap:
      type: object
      properties:
        map_id:
          type: string
        matter_id:
          type: string
        wallets:
          type: array
          items:
            type: object
            properties:
              wallet_id:
                type: string
              address:
                type: string
              network:
                type: string
              role:
                type: string
              confidence:
                type: string
              source_refs:
                type: string
        token_exposures:
          type: array
          items:
            type: object
            properties:
              asset:
                type: string
              network:
                type: string
              amount:
                type: number
              usd_value:
                type: number
              wallet:
                type: string
        exchange_hypotheses:
          type: array
          items:
            type: object
            properties:
              hypothesis_id:
                type: string
              exchange:
                type: string
              wallet:
                type: string
              basis:
                type: string
              confidence:
                type: string
              packet_readiness:
                type: string
              source_refs:
                type: string
        stablecoin_exposure:
          type: array
          items:
            type: object
            properties:
              issuer:
                type: string
              asset:
                type: string
              network:
                type: string
              wallet:
                type: string
              amount:
                type: string
              freeze_capability_notes:
                type: string
              remediation_candidates:
                type: string
              review_required:
                type: string
        review_state:
          type: object
          properties:
            review_required:
              type: boolean
            review_status:
              type: string
            review_owner:
              type: string
            review_notes:
              type: string
    IssuerRemediation:
      type: object
      properties:
        remediation_id:
          type: string
        matter_id:
          type: string
        issuer:
          type: string
        asset:
          type: string
        network:
          type: string
        action_type:
          type: string
        status:
          type: string
        destination_wallet_certificate_id:
          type: string
    SanctionsReview:
      type: object
      properties:
        review_id:
          type: string
        matter_id:
          type: string
        status:
          type: string
        blocked_property_analysis:
          type: string
        ofac_report_required:
          type: boolean
        review_state:
          type: object
          properties:
            review_required:
              type: boolean
            review_status:
              type: string
            review_owner:
              type: string
            review_notes:
              type: string
    PacketExport:
      type: object
      properties:
        export_id:
          type: string
        object_type:
          type: string
        object_id:
          type: string
        format:
          type: string
        status:
          type: string
        download_url:
          type: string
        audit_id:
          type: string
    AuditEvent:
      type: object
      properties:
        event_id:
          type: string
        matter_id:
          type: string
        event_type:
          type: string
        actor_id:
          type: string
        object_type:
          type: string
        object_id:
          type: string
        timestamp:
          type: string
          format: date-time
        details:
          type: object
          additionalProperties: true
    NetworkAttribution:
      type: object
      properties:
        network_attribution_id:
          type: string
        matter_id:
          type: string
        wallet_address:
          type: string
        signal_type:
          type: string
        source:
          type: string
        legal_process_id:
          type: string
        timestamp:
          type: string
          format: date-time
        confidence_level:
          type: string
    RelationshipList:
      type: object
      description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            type: object
            properties:
              relationship_id:
                type: string
              counterparty_type:
                type: string
              counterparty_name:
                type: string
              channel_type:
                type: string
              usable_by_meridian:
                type: string
              usable_by_counsel:
                type: string
              usable_by_law_enforcement:
                type: string
              authorized_submitter_required:
                type: string
        has_more:
          type: boolean
      required:
        - object
        - data
        - has_more
    ActionList:
      type: object
      description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            type: object
            properties:
              action_id:
                type: string
              matter_id:
                type: string
              campaign_id:
                type: string
              type:
                type: string
              title:
                type: string
              owner_id:
                type: string
              priority:
                type: string
              status:
                type: string
        has_more:
          type: boolean
      required:
        - object
        - data
        - has_more
    ListEnvelope:
      type: object
      description: List envelope. Walk forward with starting_after; has_more tells you when to stop.
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            type: object
        has_more:
          type: boolean
      required:
        - object
        - data
        - has_more
  parameters: {}
security:
  - protocol_key: []
x-md-headers:
  MD-Version: Date-pinned API version, e.g. 2026-06-11. Pinned at first call if omitted.
  Idempotency-Key: Safe retries on all write operations (24h replay window).
  MD-Request-Id: Returned on every response; quote it in support and audit queries.
  MD-Signature: "HMAC-SHA256 webhook signature: t=<ts>,v1=<sig>."
