openapi: 3.1.0
info:
  title: NorthPoint Hydra API
  version: v1
  summary: Crypto judgment enforcement, documented.
  description: |
    This OpenAPI file documents the NorthPoint Hydra API surface.
    It is a developer-preview artifact and does not imply open production access.

    Hydra turns a civil judgment into a recovery workflow:
    matters, judgments, debtor graphs, attribution, packets, Claw campaigns,
    ledger events, and audit.
  contact:
    name: Kinetic Systems
    url: https://kineticsystems.uk
servers:
  - url: https://kineticsystems.uk
    description: Documentation host
  - url: https://api.kineticsystems.uk
    description: Planned API host when enabled
security:
  - ApiKeyAuth: []
tags:
  - name: Health
  - name: Matters
  - name: Judgments
  - name: Attribution
  - name: Claw
  - name: Packets
  - name: Issuer Remediation
  - name: Ledger
  - name: Audit
paths:
  /v1/health:
    get:
      tags: [Health]
      summary: Check service health.
      responses:
        '200':
          description: Health status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
  /v1/matters:
    get:
      tags: [Matters]
      summary: List recovery matters.
      responses:
        '200':
          description: Matter list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatterList'
    post:
      tags: [Matters]
      summary: Create a recovery matter.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMatterRequest'
      responses:
        '201':
          description: Matter created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Matter'
  /v1/judgments/intake:
    post:
      tags: [Judgments]
      summary: Intake a judgment package.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JudgmentIntakeRequest'
      responses:
        '202':
          description: Intake accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
  /v1/attribution/graphs:
    post:
      tags: [Attribution]
      summary: Build an attribution graph for a matter.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildAttributionGraphRequest'
      responses:
        '202':
          description: Graph build accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
  /v1/claw/campaigns:
    post:
      tags: [Claw]
      summary: Start or update a Claw campaign.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClawCampaignRequest'
      responses:
        '201':
          description: Campaign created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClawCampaign'
  /v1/packets/exchange-intercept:
    post:
      tags: [Packets]
      summary: Generate an exchange packet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePacketRequest'
      responses:
        '201':
          description: Packet created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Packet'
  /v1/issuer-remediation/freeze-packet:
    post:
      tags: [Issuer Remediation]
      summary: Generate a freeze packet for issuer review.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIssuerFreezePacketRequest'
      responses:
        '201':
          description: Freeze packet created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Packet'
  /v1/ledger/events:
    post:
      tags: [Ledger]
      summary: Record a recovery event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLedgerEventRequest'
      responses:
        '201':
          description: Ledger event recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerEvent'
  /v1/audit/{matter_id}:
    get:
      tags: [Audit]
      summary: Retrieve the audit stream for a matter.
      parameters:
        - name: matter_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Audit stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventList'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          example: ok
        product:
          type: string
          example: NorthPoint Hydra
        environment:
          type: string
          example: developer-preview
    JobAccepted:
      type: object
      properties:
        job_id:
          type: string
        status:
          type: string
          example: accepted
    Matter:
      type: object
      properties:
        matter_id:
          type: string
        name:
          type: string
        judgment_status:
          type: string
        review_state:
          type: string
        created_at:
          type: string
          format: date-time
    MatterList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Matter'
    CreateMatterRequest:
      type: object
      required: [name, claimant_name]
      properties:
        name:
          type: string
        claimant_name:
          type: string
        jurisdiction:
          type: string
        notes:
          type: string
    JudgmentIntakeRequest:
      type: object
      required: [matter_id, judgment_reference, amount]
      properties:
        matter_id:
          type: string
        judgment_reference:
          type: string
        amount:
          type: number
        currency:
          type: string
          example: USD
        source_documents:
          type: array
          items:
            type: string
    BuildAttributionGraphRequest:
      type: object
      required: [matter_id]
      properties:
        matter_id:
          type: string
        wallet_addresses:
          type: array
          items:
            type: string
        source_refs:
          type: array
          items:
            type: string
    CreateClawCampaignRequest:
      type: object
      required: [matter_id, level, objective]
      properties:
        matter_id:
          type: string
        level:
          type: integer
          minimum: 0
          maximum: 6
        objective:
          type: string
        owner:
          type: string
    ClawCampaign:
      type: object
      properties:
        campaign_id:
          type: string
        matter_id:
          type: string
        level:
          type: integer
        objective:
          type: string
        status:
          type: string
    CreatePacketRequest:
      type: object
      required: [matter_id, packet_type]
      properties:
        matter_id:
          type: string
        packet_type:
          type: string
          example: exchange_intercept
        destination:
          type: string
        review_owner:
          type: string
    CreateIssuerFreezePacketRequest:
      type: object
      required: [matter_id, issuer_name, token_contract]
      properties:
        matter_id:
          type: string
        issuer_name:
          type: string
        token_contract:
          type: string
        requested_action:
          type: string
          example: freeze
    Packet:
      type: object
      properties:
        packet_id:
          type: string
        matter_id:
          type: string
        packet_type:
          type: string
        status:
          type: string
        review_state:
          type: string
    CreateLedgerEventRequest:
      type: object
      required: [matter_id, event_type, asset, amount]
      properties:
        matter_id:
          type: string
        event_type:
          type: string
          enum: [frozen, blocked, recovered, remitted]
        asset:
          type: string
        amount:
          type: number
        notes:
          type: string
    LedgerEvent:
      type: object
      properties:
        event_id:
          type: string
        matter_id:
          type: string
        event_type:
          type: string
        asset:
          type: string
        amount:
          type: number
        recorded_at:
          type: string
          format: date-time
    AuditEvent:
      type: object
      properties:
        event_id:
          type: string
        matter_id:
          type: string
        event_type:
          type: string
        actor:
          type: string
        object_type:
          type: string
        object_id:
          type: string
        timestamp:
          type: string
          format: date-time
        details:
          type: object
          additionalProperties: true
    AuditEventList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'