AxonFlow US Insurance Compliance API

openapi: 3.2.0
info:
  title: Axonflow US Insurance Compliance API
  version: 11.1.0
  contact:
    name: AxonFlow Support
    url: https://getaxonflow.com/support
  license:
    name: Business Source License 1.1
    url: https://github.com/getaxonflow/axonflow/blob/main/LICENSE
  description: 'Operations tagged US Insurance Compliance across 2 of this provider''s published API definitions: axonflow-orchestrator-api.yaml, axonflow-orchestrator-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://orchestrator.getaxonflow.com
  description: Production (SaaS)
- url: http://localhost:8081
  description: Local Development
tags:
- name: US Insurance Compliance
  description: 'NAIC AI Systems Evaluation Tool exhibit evidence for US insurers, with

    the NYDFS Circular Letter No. 7 and Colorado Regulation 10-1-1 annexes.

    Read-only: these routes report AI system surfaces, human oversight and

    consumer data classes observed in governed traffic. AxonFlow performs no

    statistical fairness testing and designates no system as high risk.'
paths:
  /api/v1/usinsurance/inventory:
    get:
      tags:
      - US Insurance Compliance
      summary: Observed AI system inventory (Exhibit A)
      description: 'Returns the AI system surfaces OBSERVED in governed traffic during the

        reporting window, with invocation counts and the governance verdicts

        recorded against them. This is the spine of NAIC Supplement Exhibit A.


        The response carries a `disclosure` string stating what the list is

        not: AxonFlow does not discover AI systems outside the gateway, so this

        is not a network-wide AI census, and it does not designate any system

        as high risk. `unattributed_invocations` reports governed activity that

        recorded no provider or model, so the item counts and the decision

        volumes can be reconciled.


        **Enterprise Feature**.'
      operationId: getUSInsuranceInventory
      parameters:
      - name: X-Org-ID
        in: header
        required: false
        description: 'Organization identifier, the authoritative scope for this route.

          Set by the AxonFlow agent from the validated client credential on

          every proxied route, so a caller cannot choose it.

          '
        schema:
          type: string
      - name: X-Tenant-ID
        in: header
        required: false
        description: 'Fallback used ONLY when `X-Org-ID` is absent, which covers

          single-identifier deployments where the two values are the same.

          When both are present the organization wins. A request carrying

          neither, or a whitespace-only value, is rejected with 400

          (`SCOPE_REQUIRED`): the org predicate is the tenant boundary on

          `audit_logs`, which has no row-level security.

          '
        schema:
          type: string
      - name: period_start
        in: query
        required: false
        description: 'Start of the reporting window, RFC3339 or `YYYY-MM-DD`. Defaults to

          90 days before `period_end`.

          '
        schema:
          type: string
      - name: period_end
        in: query
        required: false
        description: End of the reporting window, RFC3339 or `YYYY-MM-DD`. Defaults to now.
        schema:
          type: string
      responses:
        '200':
          description: Observed AI system inventory (Exhibit A)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceInventoryResponse'
              example:
                items:
                - system: anthropic / claude-3-5-sonnet
                  provider: anthropic
                  model: claude-3-5-sonnet
                  request_types:
                  - llm_chat
                  invocations: 120
                  decision_counts:
                    allowed: 100
                    blocked: 12
                    redacted: 5
                    needs_approval: 3
                  first_seen: '2026-06-01T00:00:00Z'
                  last_seen: '2026-08-26T00:00:00Z'
                total: 1
                unattributed_invocations: 9
                period_start: '2026-06-01T00:00:00Z'
                period_end: '2026-08-26T00:00:00Z'
                completeness:
                  complete: true
                  truncated: false
                  unavailable: false
                disclosure: This inventory lists the model surfaces observed in traffic that routed through AxonFlow.
        '400':
          description: Missing organization scope (`SCOPE_REQUIRED`) or an invalid window (`INVALID_PERIOD`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
        '405':
          description: The US insurance read routes are GET-only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
        '503':
          description: The module is not available on this deployment (`USINSURANCE_NOT_AVAILABLE`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
    servers:
    - url: https://orchestrator.getaxonflow.com
      description: Production (SaaS)
    - url: http://localhost:8081
      description: Local Development
  /api/v1/usinsurance/oversight:
    get:
      tags:
      - US Insurance Compliance
      summary: Human oversight register with exceptions and overrides (Exhibits B and C)
      description: 'Returns the human oversight register for the window: approvals,

        rejections, expiries and overrides, with the reviewer identity and role

        the platform recorded. Rows carrying an override trail are the

        exception history NAIC Supplement Exhibit C and NYDFS CL7 ask for, and

        are flagged with `is_exception`.


        Unreviewed rows are INCLUDED and counted in `unresolved`: how many

        holds were never resolved is a market-conduct question, and filtering

        them out would make every report show perfect resolution.


        **Enterprise Feature**.'
      operationId: getUSInsuranceOversight
      parameters:
      - name: X-Org-ID
        in: header
        required: false
        description: 'Organization identifier, the authoritative scope for this route.

          Set by the AxonFlow agent from the validated client credential on

          every proxied route, so a caller cannot choose it.

          '
        schema:
          type: string
      - name: X-Tenant-ID
        in: header
        required: false
        description: 'Fallback used ONLY when `X-Org-ID` is absent, which covers

          single-identifier deployments where the two values are the same.

          When both are present the organization wins. A request carrying

          neither, or a whitespace-only value, is rejected with 400

          (`SCOPE_REQUIRED`): the org predicate is the tenant boundary on

          `audit_logs`, which has no row-level security.

          '
        schema:
          type: string
      - name: period_start
        in: query
        required: false
        description: 'Start of the reporting window, RFC3339 or `YYYY-MM-DD`. Defaults to

          90 days before `period_end`.

          '
        schema:
          type: string
      - name: period_end
        in: query
        required: false
        description: End of the reporting window, RFC3339 or `YYYY-MM-DD`. Defaults to now.
        schema:
          type: string
      responses:
        '200':
          description: Human oversight register with exceptions and overrides (Exhibits B and C)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceOversightResponse'
              example:
                items:
                - id: '1'
                  request_id: 0f4b2c4a-1d1e-4a3b-9a1a-2f3c4d5e6f70
                  created_at: '2026-08-20T09:00:00Z'
                  request_type: llm_chat
                  trigger_reason: policy hold
                  policy_id: underwriting_guard
                  policy_name: Underwriting guard
                  severity: critical
                  status: overridden
                  reviewer_id: reviewer-1
                  reviewer_role: underwriter
                  reviewed_at: '2026-08-20T10:00:00Z'
                  review_latency_ms: 3600000
                  is_exception: true
                  override_authorized_by: risk-officer
                  override_justification: documented regulatory exception
                total: 1
                exceptions: 1
                unresolved: 0
                period_start: '2026-06-01T00:00:00Z'
                period_end: '2026-08-26T00:00:00Z'
                completeness:
                  complete: true
                  truncated: false
                  unavailable: false
        '400':
          description: Missing organization scope (`SCOPE_REQUIRED`) or an invalid window (`INVALID_PERIOD`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
        '405':
          description: The US insurance read routes are GET-only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
        '503':
          description: The module is not available on this deployment (`USINSURANCE_NOT_AVAILABLE`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
    servers:
    - url: https://orchestrator.getaxonflow.com
      description: Production (SaaS)
    - url: http://localhost:8081
      description: Local Development
  /api/v1/usinsurance/data-sources:
    get:
      tags:
      - US Insurance Compliance
      summary: Consumer data classes observed in governed traffic (Exhibit D)
      description: 'Returns the classes of consumer data detected and acted on in governed

        traffic during the window. This is the measurable half of NAIC

        Supplement Exhibit D.


        The response carries a `disclosure` string stating what the list is

        not: it is not the carrier''s data-source inventory and it is not an

        external consumer data and information source (ECDIS) register. Both

        remain the carrier''s own records.


        **Enterprise Feature**.'
      operationId: getUSInsuranceDataSources
      parameters:
      - name: X-Org-ID
        in: header
        required: false
        description: 'Organization identifier, the authoritative scope for this route.

          Set by the AxonFlow agent from the validated client credential on

          every proxied route, so a caller cannot choose it.

          '
        schema:
          type: string
      - name: X-Tenant-ID
        in: header
        required: false
        description: 'Fallback used ONLY when `X-Org-ID` is absent, which covers

          single-identifier deployments where the two values are the same.

          When both are present the organization wins. A request carrying

          neither, or a whitespace-only value, is rejected with 400

          (`SCOPE_REQUIRED`): the org predicate is the tenant boundary on

          `audit_logs`, which has no row-level security.

          '
        schema:
          type: string
      - name: period_start
        in: query
        required: false
        description: 'Start of the reporting window, RFC3339 or `YYYY-MM-DD`. Defaults to

          90 days before `period_end`.

          '
        schema:
          type: string
      - name: period_end
        in: query
        required: false
        description: End of the reporting window, RFC3339 or `YYYY-MM-DD`. Defaults to now.
        schema:
          type: string
      responses:
        '200':
          description: Consumer data classes observed in governed traffic (Exhibit D)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceDataSourcesResponse'
              example:
                items:
                - category: ssn
                  occurrences: 12
                  first_seen: '2026-06-01T00:00:00Z'
                  last_seen: '2026-08-26T00:00:00Z'
                total: 1
                period_start: '2026-06-01T00:00:00Z'
                period_end: '2026-08-26T00:00:00Z'
                completeness:
                  complete: true
                  truncated: false
                  unavailable: false
                disclosure: These are the consumer data classes detected in governed traffic.
        '400':
          description: Missing organization scope (`SCOPE_REQUIRED`) or an invalid window (`INVALID_PERIOD`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
        '405':
          description: The US insurance read routes are GET-only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
        '503':
          description: The module is not available on this deployment (`USINSURANCE_NOT_AVAILABLE`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USInsuranceAPIError'
    servers:
    - url: https://orchestrator.getaxonflow.com
      description: Production (SaaS)
    - url: http://localhost:8081
      description: Local Development
components:
  schemas:
    USInsuranceDataCategoryItem:
      type: object
      properties:
        category:
          type: string
        occurrences:
          type: integer
        first_seen:
          type: string
          format: date-time
        last_seen:
          type: string
          format: date-time
    USInsuranceOversightItem:
      type: object
      properties:
        id:
          type: string
        request_id:
          type: string
        created_at:
          type: string
          format: date-time
        request_type:
          type: string
        trigger_reason:
          type: string
        policy_id:
          type: string
        policy_name:
          type: string
        severity:
          type: string
        status:
          type: string
        reviewer_id:
          type: string
        reviewer_role:
          type: string
        reviewed_at:
          type: string
          format: date-time
          description: Omitted when the row was never reviewed.
        review_latency_ms:
          type: integer
          format: int64
          description: Omitted when the row was never reviewed.
        is_exception:
          type: boolean
          description: 'True when the platform recorded the overridden status, OR recorded

            an override trail under another status. Both arms matter: a row

            carrying evidence must not drop out of the exception exhibit

            because its status string differs.

            '
        override_authorized_by:
          type: string
          description: Omitted when none was recorded.
        override_justification:
          type: string
          description: Surfaced verbatim. Omitted when none was recorded.
    USInsuranceAPIError:
      type: object
      description: US insurance module error envelope
      properties:
        error:
          type: string
          description: Human-readable message. Never carries the underlying database error.
        error_code:
          type: string
          description: 'Stable machine-readable code: SCOPE_REQUIRED, INVALID_PERIOD,

            USINSURANCE_NOT_AVAILABLE or INTERNAL_ERROR.

            '
      required:
      - error
      - error_code
    USInsuranceInventoryItem:
      type: object
      description: 'One AI system surface observed in governed traffic. The identity is the

        recorded provider and model pair, which is the only system identity the

        platform holds; a carrier''s own system name is never invented here.

        '
      properties:
        system:
          type: string
          description: Rendered identity, "provider / model".
        provider:
          type: string
        model:
          type: string
        request_types:
          type: array
          items:
            type: string
        invocations:
          type: integer
        decision_counts:
          type: object
          additionalProperties:
            type: integer
          description: Counts keyed by the platform's own policy_decision vocabulary.
        first_seen:
          type: string
          format: date-time
        last_seen:
          type: string
          format: date-time
    USInsuranceInventoryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/USInsuranceInventoryItem'
        total:
          type: integer
        unattributed_invocations:
          type: integer
          description: 'Governed activity that recorded no provider and no model, so it

            could not be attributed to a model surface. Reported rather than

            dropped so the item counts and the decision volumes reconcile.

            '
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        completeness:
          $ref: '#/components/schemas/USInsuranceCompleteness'
        disclosure:
          type: string
          description: 'States what this list is not. AxonFlow does not discover AI systems

            outside the gateway and does not designate any system as high risk.

            '
    USInsuranceCompleteness:
      type: object
      description: 'The per-response completeness signal. It is ALWAYS present, populated

        or not, so a client never has to infer the good case from an absent

        field. `unavailable` means the backing surface is not present on this

        deployment, which is NOT the same as an empty result.

        '
      properties:
        complete:
          type: boolean
          description: True when the read succeeded and returned everything it matched.
        truncated:
          type: boolean
          description: True when the row cap was reached, so the items are a subset.
        unavailable:
          type: boolean
          description: True when the backing surface is absent on this deployment.
        note:
          type: string
          description: One sentence explaining a non-complete answer. Omitted when complete.
      required:
      - complete
      - truncated
      - unavailable
    USInsuranceDataSourcesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/USInsuranceDataCategoryItem'
        total:
          type: integer
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        completeness:
          $ref: '#/components/schemas/USInsuranceCompleteness'
        disclosure:
          type: string
          description: 'States what this list is not: not the carrier''s data-source

            inventory and not an ECDIS register.

            '
    USInsuranceOversightResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/USInsuranceOversightItem'
        total:
          type: integer
        exceptions:
          type: integer
          description: Count of items carrying an override trail.
        unresolved:
          type: integer
          description: Count of items that were never reviewed.
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        completeness:
          $ref: '#/components/schemas/USInsuranceCompleteness'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: OAuth2-style client credentials (clientId:clientSecret)
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enterprise JWT token (see /scripts/generate-jwt.sh)
x-refined-from:
- axonflow-orchestrator-api.yaml
- axonflow-orchestrator-openapi.yml