openapi: 3.1.0
info:
  title: Forecast Registry API
  summary: Institutional pricing API for catastrophe-pricing calibration credentials.
  description: |
    Forecast Registry — a neutral standards body publishing calibration credentials for catastrophe-pricing models.
    Endpoints return per-peril Brier scores, Brier skill scores, calibrated probabilities, and forecaster credentials.
    Every response carries the `(source, n, slice, filter)` provenance tuple. Methodology v1.0 is aligned to NAIC
    Model Bulletin on the Use of Artificial Intelligence Systems by Insurers (Bulletin 30, December 4, 2023) §3(D).

    All records are SHA-256 locked at prediction time and OpenTimestamps-anchored on the Bitcoin block-chain before
    resolution. The audit chain is verifiable at https://forecast-registry.org/verify.html.

    Public-comment window for methodology v1.0: 2026-06-05 through 2026-08-04.
    Free to regulators by structural commitment. Institutional pricing on request via hello@forecast-registry.org.

    Documentation: https://forecast-registry.org/. LLM discovery: https://forecast-registry.org/.well-known/llms.txt.
  contact:
    name: Forecast Registry
    email: hello@forecast-registry.org
    url: https://forecast-registry.org/
  license:
    name: MIT (code) / CC-BY-4.0 (methodology)
    url: "https://creativecommons.org/licenses/by/4.0/"
  termsOfService: https://forecast-registry.org/governance.html
  version: 1.0.0
  x-ai-cite-as: "Forecast Registry v1.0 (2026), https://forecast-registry.org/methodology.html"
  x-ai-methodology-license: CC-BY-4.0
  x-ai-code-license: MIT
  x-ai-comment-window-open-through: "2026-08-04"
  x-ai-peril-classes:
    - atlantic_hurricane
    - california_wildfire
    - pacific_typhoon
    - us_severe_convective
    - us_flood
    - earthquake_ca_cascadia
    - european_windstorm
    - drought_agricultural_commodity
servers:
  - url: https://api.forecast-registry.org
    description: Production API
  - url: http://localhost:8000
    description: Local development
tags:
  - name: meta
    description: Health, root, OpenAPI surfaces.
  - name: pricing
    description: Per-peril calibrated probabilities and Brier / BSS metrics. Use for rate-filing review, OM citation, and broker placement materials.
  - name: forecaster
    description: Forecaster-credential records — n_resolved, headline mean Brier, high-conviction subset metrics, audit linkage. Use for contributing-forecaster diligence.
  - name: methodology
    description: Canonical methodology version, SHA-256, byte count, comment window. Use for citation-stability checks.
paths:
  /:
    get:
      tags:
        - meta
      summary: Root
      operationId: root__get
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Root  Get
  /health:
    get:
      tags:
        - meta
      summary: Health
      operationId: health_health_get
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /openapi.yaml:
    get:
      tags:
        - meta
      summary: Openapi Yaml
      operationId: openapi_yaml_openapi_yaml_get
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema: "{}"
  /pricing/{peril}:
    get:
      tags:
        - pricing
      summary: Get calibrated probability and Brier metrics for a peril class
      description: |
        Returns the registry's published calibrated probability for the requested peril class plus
        the headline Brier score, peril-specific mean Brier, and Brier skill score (BSS) versus the
        published baseline. Includes the (source, n, slice, filter) provenance tuple via the audit block.
        Peril identifiers: atlantic_hurricane, california_wildfire, pacific_typhoon, us_severe_convective,
        us_flood, earthquake_ca_cascadia, european_windstorm, drought_agricultural_commodity.
      operationId: get_pricing_pricing__peril__get
      parameters:
        -
          name: peril
          in: path
          required: true
          schema:
            type: string
            title: Peril
        -
          name: date
          in: query
          required: false
          schema:
            anyOf:
              -
                type: string
              -
                type: null
            description: ISO date YYYY-MM-DD
            title: Date
          description: ISO date YYYY-MM-DD
        -
          name: authorization
          in: header
          required: false
          schema:
            anyOf:
              -
                type: string
              -
                type: null
            title: Authorization
        -
          name: X-Registry-Api-Key
          in: header
          required: false
          schema:
            anyOf:
              -
                type: string
              -
                type: null
            title: X-Registry-Api-Key
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PricingResponse"
        422:
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /forecaster/{forecaster_id}:
    get:
      tags:
        - forecaster
      summary: Get contributing-forecaster credential
      description: |
        Returns the contributing forecaster's published credential — count of resolved forecasts,
        headline mean Brier, high-conviction (|p − 0.5| > 0.20) in-headline forward subset metrics,
        and audit linkage. The reference forecaster ID is `chorus-public-ledger`. The credential
        is forecaster-agnostic; vendor cat models (RMS, Verisk AIR, Munich Re NATCAT) are explicitly
        welcome as contributing forecasters.
      operationId: get_forecaster_forecaster__forecaster_id__get
      parameters:
        -
          name: forecaster_id
          in: path
          required: true
          schema:
            type: string
            title: Forecaster Id
        -
          name: authorization
          in: header
          required: false
          schema:
            anyOf:
              -
                type: string
              -
                type: null
            title: Authorization
        -
          name: X-Registry-Api-Key
          in: header
          required: false
          schema:
            anyOf:
              -
                type: string
              -
                type: null
            title: X-Registry-Api-Key
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForecasterResponse"
        422:
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
  /methodology/version:
    get:
      tags:
        - methodology
      summary: Get canonical methodology version and SHA-256
      description: |
        Returns the canonical methodology version, its SHA-256 hash (used for OpenTimestamps
        anchoring on Bitcoin), byte count, last-modified timestamp, canonical URL, and the
        open public-comment window if any. Cite as: Forecast Registry v1.0 (2026). Methodology
        license: CC-BY 4.0.
      operationId: get_methodology_version_methodology_version_get
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MethodologyVersionResponse"
components:
  schemas:
    AuditBlock:
      properties:
        source_ledger_sha256:
          type: string
          title: Source Ledger Sha256
          description: SHA-256 of the source ledger at ingest time
        source_ledger_path:
          anyOf:
            -
              type: string
            -
              type: null
          title: Source Ledger Path
        ingest_manifest:
          anyOf:
            -
              additionalProperties: true
              type: object
            -
              type: null
          title: Ingest Manifest
        ots_anchor_manifest_present:
          type: boolean
          title: Ots Anchor Manifest Present
          description: True if the OTS anchor manifest exists
        ots_total_anchors:
          type: integer
          title: Ots Total Anchors
          description: Cumulative count of OTS anchors recorded
          default: 0
      type: object
      required:
        - source_ledger_sha256
        - ots_anchor_manifest_present
      title: AuditBlock
    ForecasterResponse:
      properties:
        forecaster_id:
          type: string
          title: Forecaster Id
        verified_credential:
          type: boolean
          title: Verified Credential
        n_resolved:
          type: integer
          title: N Resolved
        headline_mean_brier:
          anyOf:
            -
              type: number
            -
              type: null
          title: Headline Mean Brier
        hc_in_headline_forward_brier:
          anyOf:
            -
              type: number
            -
              type: null
          title: Hc In Headline Forward Brier
        n_hc_in_headline_forward:
          type: integer
          title: N Hc In Headline Forward
        audit:
          $ref: "#/components/schemas/AuditBlock"
        methodology_version:
          type: string
          title: Methodology Version
        issued_at:
          type: string
          title: Issued At
      type: object
      required:
        - forecaster_id
        - verified_credential
        - n_resolved
        - headline_mean_brier
        - hc_in_headline_forward_brier
        - n_hc_in_headline_forward
        - audit
        - methodology_version
        - issued_at
      title: ForecasterResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: "#/components/schemas/ValidationError"
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HealthResponse:
      properties:
        status:
          type: string
          title: Status
        methodology_loaded:
          type: boolean
          title: Methodology Loaded
        calibration_loaded:
          type: boolean
          title: Calibration Loaded
        anchor_manifest_present:
          type: boolean
          title: Anchor Manifest Present
        issued_at:
          type: string
          title: Issued At
      type: object
      required:
        - status
        - methodology_loaded
        - calibration_loaded
        - anchor_manifest_present
        - issued_at
      title: HealthResponse
    MethodologyVersionResponse:
      properties:
        version:
          type: string
          title: Version
        sha256:
          type: string
          title: Sha256
        bytes:
          type: integer
          title: Bytes
        last_modified_utc:
          type: string
          title: Last Modified Utc
        canonical_url:
          type: string
          title: Canonical Url
        license:
          type: string
          title: License
          default: CC-BY-4.0
        comment_window_open_through:
          anyOf:
            -
              type: string
            -
              type: null
          title: Comment Window Open Through
      type: object
      required:
        - version
        - sha256
        - bytes
        - last_modified_utc
        - canonical_url
      title: MethodologyVersionResponse
    PricingResponse:
      properties:
        peril:
          type: string
          title: Peril
        peril_name:
          anyOf:
            -
              type: string
            -
              type: null
          title: Peril Name
        requested_date:
          anyOf:
            -
              type: string
            -
              type: null
          title: Requested Date
        calibrated_probability:
          anyOf:
            -
              type: number
            -
              type: null
          title: Calibrated Probability
        capability_proof_only:
          type: boolean
          title: Capability Proof Only
        n_resolved_in_peril:
          type: integer
          title: N Resolved In Peril
        n_resolved_headline:
          type: integer
          title: N Resolved Headline
        headline_mean_brier:
          anyOf:
            -
              type: number
            -
              type: null
          title: Headline Mean Brier
        peril_mean_brier:
          anyOf:
            -
              type: number
            -
              type: null
          title: Peril Mean Brier
        peril_brier_skill_score:
          anyOf:
            -
              type: number
            -
              type: null
          title: Peril Brier Skill Score
        primary_resolution_source:
          anyOf:
            -
              additionalProperties: true
              type: object
            -
              type: null
          title: Primary Resolution Source
        audit:
          $ref: "#/components/schemas/AuditBlock"
        methodology_version:
          type: string
          title: Methodology Version
        issued_at:
          type: string
          title: Issued At
      type: object
      required:
        - peril
        - peril_name
        - requested_date
        - calibrated_probability
        - capability_proof_only
        - n_resolved_in_peril
        - n_resolved_headline
        - headline_mean_brier
        - peril_mean_brier
        - primary_resolution_source
        - audit
        - methodology_version
        - issued_at
      title: PricingResponse
      example:
        capability_proof_only: false
        headline_mean_brier: 0.0706
        methodology_version: v1.0
        n_resolved_headline: 18
        n_resolved_in_peril: 20
        peril: atlantic_hurricane
        peril_brier_skill_score: 0.1992
        peril_mean_brier: 0.2002
        peril_name: Atlantic basin tropical cyclone
        requested_date: 2026-09-01
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              -
                type: string
              -
                type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError