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

# Read a policy



## OpenAPI

````yaml GET /policies/{productId}/{policyId}
openapi: 3.0.3
info:
  title: Lumina Protocol API
  version: 0.1.0
  description: >-
    Programmatic access to Lumina (Base mainnet 8453). Discover canonical
    contract addresses via GET /health.


    ## Authentication


    - Public endpoints (`/health`, `/products`, `/policies/...`) require no
    auth.

    - Authenticated endpoints under `/api/v1/*` (except `/api/v1/agent/onboard`)
    require an `x-api-key` header. Obtain one via `POST /api/v1/agent/onboard`
    (signed by your wallet) or have an admin call `POST /api/v1/keys/generate`.

    - Admin endpoints under `/api/v1/keys` require an `x-admin-token` header.


    ## Idempotency


    `POST /api/v1/policies` honours an optional `Idempotency-Key` header. A
    repeated call with the same key (per agent) returns the cached response.


    ## Numeric encoding


    All on-chain integer values (USDC base units, LUMINA wei, prices, etc.) are
    returned as decimal strings to avoid JavaScript Number precision loss.
  contact:
    url: https://www.lumina-org.com
  license:
    name: Proprietary
servers:
  - url: https://lumina-api-production-ac85.up.railway.app
    description: Production (Base mainnet 8453)
  - url: http://localhost:8080
    description: Local dev
security: []
tags:
  - name: discovery
    description: Service health & configuration discovery
  - name: products
    description: Insurance product catalogue and quotes
  - name: policies
    description: Buy and read insurance policies
  - name: redeem
    description: Verify and record bond redemptions
  - name: bonds
    description: List bonds (ERC-1155 epochs) for a wallet
  - name: marketplace
    description: 'Secondary marketplace: list / buy / browse bonds'
  - name: oracle
    description: Off-chain price oracle signer
  - name: keys
    description: 'Admin: API key issuance & revocation'
  - name: agent
    description: Self-service supervisor surface for agents/wallets
  - name: webhooks
    description: Subscribe to event push (HMAC-signed POST callbacks)
  - name: sandbox
    description: Public 'Try It' surface — pre-funded wallet, $1 cap
paths:
  /policies/{productId}/{policyId}:
    get:
      tags:
        - policies
      summary: Read a policy by composite key
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Bytes32'
        - name: policyId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/DecimalString'
      responses:
        '200':
          description: Policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          description: Invalid path parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Policy not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
components:
  schemas:
    Bytes32:
      type: string
      pattern: ^0x[0-9a-fA-F]{64}$
      description: 32-byte 0x-prefixed hex string (e.g. a productId or txHash).
      example: '0x0000000000000000000000000000000000000000000000000000000000000000'
    DecimalString:
      type: string
      pattern: ^\d+$
      description: >-
        A non-negative integer encoded as a decimal string (used for token
        amounts, prices, and other on-chain bigint values).
      example: '1000000'
    Policy:
      type: object
      required:
        - productId
        - policyId
        - shield
        - buyer
        - holder
        - coverageAmount
        - payoutAmount
        - premiumPaid
        - createdAt
        - expiresAt
        - status
        - triggered
        - expired
      properties:
        productId:
          $ref: '#/components/schemas/Bytes32'
        productName:
          type: string
          description: Human-readable name derived from PRODUCT_ID preimage.
        policyId:
          $ref: '#/components/schemas/DecimalString'
        shield:
          $ref: '#/components/schemas/Address'
        buyer:
          $ref: '#/components/schemas/Address'
        holder:
          $ref: '#/components/schemas/Address'
        coverageAmount:
          $ref: '#/components/schemas/DecimalString'
        payoutAmount:
          $ref: '#/components/schemas/DecimalString'
        premiumPaid:
          $ref: '#/components/schemas/DecimalString'
          description: USDC base units (6-dec).
        purchasedAt:
          $ref: '#/components/schemas/DecimalString'
          description: Unix seconds.
        createdAt:
          $ref: '#/components/schemas/DecimalString'
          description: Unix seconds.
        waitingEndsAt:
          type: string
          nullable: true
          description: Unix-seconds string when the waiting period ends, or null.
        expiresAt:
          $ref: '#/components/schemas/DecimalString'
          description: Unix seconds.
        status:
          type: string
          enum:
            - Waiting
            - Active
            - Triggered
            - Expired
            - Cancelled
        triggered:
          type: boolean
        expired:
          type: boolean
        productActive:
          type: boolean
        priceSnapshot:
          $ref: '#/components/schemas/DecimalString'
          description: >-
            LUMINA/USD 18-dec snapshot at purchase. '0' for legacy V5.0
            policies.
        triggeredAt:
          type: string
          nullable: true
          description: Unix-seconds when triggered, or null.
        bondId:
          type: string
          nullable: true
          description: BondVault epochId minted at trigger, or null.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            Machine-readable error code (e.g. validation_error,
            unauthenticated).
          example: validation_error
        message:
          type: string
          description: Human-readable explanation.
        details:
          type: array
          description: >-
            Per-field validation issues (zod path + message). Only present for
            validation_error.
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
          nullable: true
    Address:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: Ethereum 0x-prefixed checksummed or lowercase address.
      example: '0x0000000000000000000000000000000000000000'

````