openapi: 3.1.0
info:
  title: Mossforge DataBroker
  version: 1.0.0
  description: >-
    Pay-per-call UK data API gated by x402 micropayments on Base mainnet. No API keys, no accounts,
    no subscriptions — sign a payment, get data back.


    Every paid endpoint returns HTTP 402 with payment requirements until a valid signed USDC payment
    is attached, then settles on-chain and returns the data in the same response cycle. A 402
    response means no funds have moved; you only pay on a 200 OK (with one documented exception:
    BUCKET_NOT_SEEDED, see that response).


    GENERATED FILE — do not edit by hand. Regenerate with `npx tsx
    scripts/openapi/generate-openapi.ts`. Utility schemas and examples are derived by running the
    actual compute functions; DVSA schemas are inferred from real captured payloads in
    scripts/openapi/fixtures/.
  contact:
    email: support@mossforge.dev
externalDocs:
  description: Human-readable README, integration examples (TypeScript & Python)
  url: https://github.com/mossforge/databroker
servers:
  - url: https://api.databroker.mossforge.dev
    description: Production (Base mainnet, eip155:8453)
tags:
  - name: meta
    description: Unauthenticated routes — health, discovery, freshness checks
  - name: dvsa-mot
    description: Full MOT history for a single UK vehicle by registration
  - name: dvsa-mot-analytics
    description: Aggregated MOT statistics by vehicle segment
  - name: utilities
    description: Deterministic utility computations and bundled-snapshot lookups
paths:
  /v1/health:
    get:
      tags:
        - meta
      summary: Uptime check
      operationId: getHealth
      responses:
        "200":
          description: Always 200 if the service is up.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  ts:
                    type: string
                    format: date-time
                required:
                  - status
                  - ts
  /v1/discover:
    get:
      tags:
        - meta
      summary: List enabled datasets and current prices
      operationId: discover
      description: No payment required. Call this first — prices are configured server-side and may change
        without notice to any static documentation, including this spec.
      responses:
        "200":
          description: Enabled datasets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  datasets:
                    type: array
                    items:
                      type: object
                      properties:
                        dataset_id:
                          type: string
                        description:
                          type: string
                        price_usdc:
                          type: string
                        scheme:
                          type: string
                          enum:
                            - exact
                            - upto
                        network:
                          type: string
                          example: eip155:8453
                        kind:
                          type: string
                          enum:
                            - cached
                            - computed
                            - bundled
                        standard:
                          type: string
                        deterministic:
                          type: boolean
                        data_source:
                          type: string
                      required:
                        - dataset_id
                        - description
                        - price_usdc
                        - scheme
                        - network
                        - kind
                  count:
                    type: integer
                required:
                  - datasets
                  - count
  /v1/{dataset}/{key}/meta:
    get:
      tags:
        - meta
      summary: Cache freshness for any dataset key — no payment
      operationId: getMeta
      parameters:
        - name: dataset
          in: path
          required: true
          schema:
            type: string
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Freshness info for whatever is currently cached (or utility provenance).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetaResponse"
        "404":
          description: ENTITY_NOT_FOUND — nothing cached for this key yet.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/dvsa-mot/{registration}:
    get:
      tags:
        - dvsa-mot
      summary: Full MOT history for a UK vehicle
      operationId: getMotHistory
      description: "First-ever lookup triggers a live on-demand DVSA fetch (typically 2–4 s) and may
        return 503 INGEST_IN_PROGRESS — retry after `retry_after_seconds`. Subsequent calls within
        the cache window return instantly from cache. Normalise the registration before calling:
        strip spaces, upper-case (`ab12 cde` → `AB12CDE`)."
      parameters:
        - name: registration
          in: path
          required: true
          schema:
            type: string
            example: AB12CDE
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - dvsa-mot
                      data:
                        $ref: "#/components/schemas/MotHistoryData"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "404":
          $ref: "#/components/responses/EntityNotFound"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/IngestInProgress"
  /v1/dvsa-mot-analytics/{key}:
    get:
      tags:
        - dvsa-mot-analytics
      summary: Aggregated MOT statistics for a vehicle segment
      operationId: getMotAnalytics
      description: "Colon-delimited, family-specific keys: `reliability:<make>`,
        `mileage:<make>:<band|year>`, `parc:<make>:<fuel>:<band|year>`, `fuelmix:<year>`,
        `colour:<make>:<year>`, `temporal`. Age bands: 0-3yr, 3-5yr, 5-8yr, 8-12yr, 12yr+. Fuels:
        petrol, diesel, electric, hybrid, other. Malformed keys are rejected with 400 before
        payment; a well-formed key for an unseeded segment returns 404 BUCKET_NOT_SEEDED after
        settlement (settle-before-serve)."
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
            example: reliability:ford
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - dvsa-mot-analytics
                      data:
                        $ref: "#/components/schemas/AnalyticsData"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "404":
          $ref: "#/components/responses/BucketNotSeeded"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-vin/{key}:
    get:
      tags:
        - utilities
      summary: VIN structural validation, North American check digit, WMI region/manufacturer, and model
        year decode (ISO 3779/3780)
      operationId: getUtilVin
      description: "Standard: ISO 3779 / ISO 3780 / FMVSS 565. Pure deterministic computation — never
        cached, never stale. Malformed keys are rejected with 400 before any payment is taken; a
        well-formed key that validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `1HGCM82633A004352`"
          schema:
            type: string
            example: 1HGCM82633A004352
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-vin
                      data:
                        $ref: "#/components/schemas/UtilVinData"
                      deterministic:
                        type: boolean
              examples:
                1HGCM82633A004352:
                  summary: 1HGCM82633A004352
                  value:
                    dataset: util-vin
                    key: 1HGCM82633A004352
                    data:
                      input: 1HGCM82633A004352
                      normalised: 1HGCM82633A004352
                      structurally_valid: true
                      check_digit_valid: true
                      wmi: 1HG
                      wmi_region: North America (United States)
                      manufacturer: Honda (USA)
                      vds: CM8263
                      vis: 3A004352
                      model_year_code: "3"
                      model_year_candidates:
                        - 2003
                        - 2033
                      plant_code: A
                      reason: null
                      standard: ISO 3779 / ISO 3780 (structure), FMVSS 565 (North American check digit)
                      caveat: The position-9 check digit is mandatory only for North American VINs; European VINs may
                        legitimately fail it. Model year codes repeat every 30 years, so both
                        candidates are returned. Manufacturer lookup covers common WMIs only.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 3779 / ISO 3780 / FMVSS 565
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                1HGCM82633A004353:
                  summary: 1HGCM82633A004353
                  value:
                    dataset: util-vin
                    key: 1HGCM82633A004353
                    data:
                      input: 1HGCM82633A004353
                      normalised: 1HGCM82633A004353
                      structurally_valid: true
                      check_digit_valid: false
                      wmi: 1HG
                      wmi_region: North America (United States)
                      manufacturer: Honda (USA)
                      vds: CM8263
                      vis: 3A004353
                      model_year_code: "3"
                      model_year_candidates:
                        - 2003
                        - 2033
                      plant_code: A
                      reason: null
                      standard: ISO 3779 / ISO 3780 (structure), FMVSS 565 (North American check digit)
                      caveat: The position-9 check digit is mandatory only for North American VINs; European VINs may
                        legitimately fail it. Model year codes repeat every 30 years, so both
                        candidates are returned. Manufacturer lookup covers common WMIs only.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 3779 / ISO 3780 / FMVSS 565
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-uk-plate/{key}:
    get:
      tags:
        - utilities
      summary: UK registration plate format validation and age decode across current, prefix, suffix and
        dateless eras
      operationId: getUtilUkPlate
      description: "Standard: DVLA registration mark formats (public rules). Pure deterministic
        computation — never cached, never stale. Malformed keys are rejected with 400 before any
        payment is taken; a well-formed key that validates to `valid: false` is a legitimate paid
        answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `AB12CDE`"
          schema:
            type: string
            example: AB12CDE
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-uk-plate
                      data:
                        $ref: "#/components/schemas/UtilUkPlateData"
                      deterministic:
                        type: boolean
              examples:
                AB12CDE:
                  summary: AB12CDE
                  value:
                    dataset: util-uk-plate
                    key: AB12CDE
                    data:
                      input: AB12CDE
                      normalised: AB12CDE
                      valid: true
                      format: current (2001+)
                      area_code: AB
                      age_identifier: "12"
                      registration_period: Mar 2012 – Aug 2012
                      notes: null
                      reason: null
                      standard: DVLA registration formats (current 2001+, prefix 1983–2001, suffix 1963–1983, dateless
                        pre-1963)
                      caveat: Format and age-identifier decode only — does not confirm the plate is issued or currently
                        assigned. Cherished transfers can put an older-format plate on a newer
                        vehicle.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: DVLA registration mark formats (public rules)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                A1:
                  summary: A1
                  value:
                    dataset: util-uk-plate
                    key: A1
                    data:
                      input: A1
                      normalised: A1
                      valid: true
                      format: dateless (pre-1963)
                      area_code: null
                      age_identifier: null
                      registration_period: null
                      notes: Dateless plates carry no age identifier; registration date cannot be derived from the mark.
                      reason: null
                      standard: DVLA registration formats (current 2001+, prefix 1983–2001, suffix 1963–1983, dateless
                        pre-1963)
                      caveat: Format and age-identifier decode only — does not confirm the plate is issued or currently
                        assigned. Cherished transfers can put an older-format plate on a newer
                        vehicle.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: DVLA registration mark formats (public rules)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-mot-due/{key}:
    get:
      tags:
        - utilities
      summary: First MOT due date from a GB first-registration date (YYYY-MM-DD), with 40-year historic
        exemption flag
      operationId: getUtilMotDue
      description: "Standard: GB MOT rules (gov.uk) / Road Vehicles Regulations 2018. Pure deterministic
        computation — never cached, never stale. Malformed keys are rejected with 400 before any
        payment is taken; a well-formed key that validates to `valid: false` is a legitimate paid
        answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `2023-05-01`"
          schema:
            type: string
            example: 2023-05-01
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-mot-due
                      data:
                        $ref: "#/components/schemas/UtilMotDueData"
                      deterministic:
                        type: boolean
              examples:
                2023-05-01:
                  summary: 2023-05-01
                  value:
                    dataset: util-mot-due
                    key: 2023-05-01
                    data:
                      input: 2023-05-01
                      first_registered: 2023-05-01
                      first_mot_due: 2026-05-01
                      first_mot_now_due: true
                      vehicle_age_years: 3
                      historic_exemption_possible: false
                      reason: null
                      standard: GB MOT rules — first test at 3 years (gov.uk); 40-year historic exemption (Road Vehicles
                        Regulations 2018)
                      caveat: Applies to standard cars/motorcycles/light vans in Great Britain. Some vehicle classes (e.g.
                        taxis, ambulances) need a first MOT at 1 year. Historic exemption requires
                        the vehicle not to be substantially changed.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: GB MOT rules (gov.uk) / Road Vehicles Regulations 2018
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                1984-05-01:
                  summary: 1984-05-01
                  value:
                    dataset: util-mot-due
                    key: 1984-05-01
                    data:
                      input: 1984-05-01
                      first_registered: 1984-05-01
                      first_mot_due: 1987-05-01
                      first_mot_now_due: true
                      vehicle_age_years: 42
                      historic_exemption_possible: true
                      reason: null
                      standard: GB MOT rules — first test at 3 years (gov.uk); 40-year historic exemption (Road Vehicles
                        Regulations 2018)
                      caveat: Applies to standard cars/motorcycles/light vans in Great Britain. Some vehicle classes (e.g.
                        taxis, ambulances) need a first MOT at 1 year. Historic exemption requires
                        the vehicle not to be substantially changed.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: GB MOT rules (gov.uk) / Road Vehicles Regulations 2018
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-tyre-size/{key}:
    get:
      tags:
        - utilities
      summary: ISO metric tyre size code parser (e.g. '205/55R16 91V') — dimensions, load index kg, speed
        rating km/h
      operationId: getUtilTyreSize
      description: "Standard: ISO metric tyre code (ETRTO). Pure deterministic computation — never cached,
        never stale. Malformed keys are rejected with 400 before any payment is taken; a well-formed
        key that validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `205/55R16 91V`"
          schema:
            type: string
            example: 205/55R16 91V
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-tyre-size
                      data:
                        $ref: "#/components/schemas/UtilTyreSizeData"
                      deterministic:
                        type: boolean
              examples:
                205_55R16_91V:
                  summary: 205/55R16 91V
                  value:
                    dataset: util-tyre-size
                    key: 205/55R16 91V
                    data:
                      input: 205/55R16 91V
                      normalised: 205/55R16 91V
                      valid: true
                      section_width_mm: 205
                      aspect_ratio_percent: 55
                      construction: radial
                      rim_diameter_inches: 16
                      overall_diameter_mm: 632
                      load_index: 91
                      max_load_kg: 615
                      speed_rating: V
                      max_speed_kmh: 240
                      reason: null
                      standard: ISO metric tyre code (ETRTO)
                      caveat: Load/speed values are the standard ETRTO table figures for the printed code.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO metric tyre code (ETRTO)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                banana:
                  summary: banana
                  value:
                    dataset: util-tyre-size
                    key: banana
                    data:
                      input: banana
                      normalised: BANANA
                      valid: false
                      section_width_mm: null
                      aspect_ratio_percent: null
                      construction: null
                      rim_diameter_inches: null
                      overall_diameter_mm: null
                      load_index: null
                      max_load_kg: null
                      speed_rating: null
                      max_speed_kmh: null
                      reason: Expected an ISO metric tyre code like '205/55R16 91V'.
                      standard: ISO metric tyre code (ETRTO)
                      caveat: Load/speed values are the standard ETRTO table figures for the printed code.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO metric tyre code (ETRTO)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-iban/{key}:
    get:
      tags:
        - utilities
      summary: IBAN validation — per-country length (SWIFT IBAN Registry) plus MOD 97-10 check digits,
        with country/BBAN parse
      operationId: getUtilIban
      description: "Standard: ISO 13616 / ISO 7064 MOD 97-10. Pure deterministic computation — never
        cached, never stale. Malformed keys are rejected with 400 before any payment is taken; a
        well-formed key that validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `GB82WEST12345698765432`"
          schema:
            type: string
            example: GB82WEST12345698765432
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-iban
                      data:
                        $ref: "#/components/schemas/UtilIbanData"
                      deterministic:
                        type: boolean
              examples:
                GB82WEST12345698765432:
                  summary: GB82WEST12345698765432
                  value:
                    dataset: util-iban
                    key: GB82WEST12345698765432
                    data:
                      input: GB82WEST12345698765432
                      normalised: GB82WEST12345698765432
                      valid: true
                      country: GB
                      check_digits: "82"
                      bban: WEST12345698765432
                      reason: null
                      standard: ISO 13616 (MOD 97-10 per ISO 7064)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 13616 / ISO 7064 MOD 97-10
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                GB00WEST12345698765432:
                  summary: GB00WEST12345698765432
                  value:
                    dataset: util-iban
                    key: GB00WEST12345698765432
                    data:
                      input: GB00WEST12345698765432
                      normalised: GB00WEST12345698765432
                      valid: false
                      country: GB
                      check_digits: "00"
                      bban: WEST12345698765432
                      reason: Check digits do not validate (MOD 97-10 remainder is not 1).
                      standard: ISO 13616 (MOD 97-10 per ISO 7064)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 13616 / ISO 7064 MOD 97-10
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-isin/{key}:
    get:
      tags:
        - utilities
      summary: ISIN validation and parse — country prefix, NSIN, Luhn check digit
      operationId: getUtilIsin
      description: "Standard: ISO 6166. Pure deterministic computation — never cached, never stale.
        Malformed keys are rejected with 400 before any payment is taken; a well-formed key that
        validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `US0378331005`"
          schema:
            type: string
            example: US0378331005
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-isin
                      data:
                        $ref: "#/components/schemas/UtilIsinData"
                      deterministic:
                        type: boolean
              examples:
                US0378331005:
                  summary: US0378331005
                  value:
                    dataset: util-isin
                    key: US0378331005
                    data:
                      input: US0378331005
                      normalised: US0378331005
                      valid: true
                      country: US
                      nsin: "037833100"
                      check_digit: "5"
                      reason: null
                      standard: ISO 6166 (Luhn over letter-expanded digits)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 6166
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                US0378331006:
                  summary: US0378331006
                  value:
                    dataset: util-isin
                    key: US0378331006
                    data:
                      input: US0378331006
                      normalised: US0378331006
                      valid: false
                      country: US
                      nsin: "037833100"
                      check_digit: "6"
                      reason: Check digit does not validate (Luhn over expanded digits).
                      standard: ISO 6166 (Luhn over letter-expanded digits)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 6166
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-cusip/{key}:
    get:
      tags:
        - utilities
      summary: "CUSIP validation and parse — issuer/issue split, mod-10 check digit with *, @, # handling"
      operationId: getUtilCusip
      description: "Standard: ANSI X9.6. Pure deterministic computation — never cached, never stale.
        Malformed keys are rejected with 400 before any payment is taken; a well-formed key that
        validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `037833100`"
          schema:
            type: string
            example: "037833100"
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-cusip
                      data:
                        $ref: "#/components/schemas/UtilCusipData"
                      deterministic:
                        type: boolean
              examples:
                "037833100":
                  summary: "037833100"
                  value:
                    dataset: util-cusip
                    key: "037833100"
                    data:
                      input: "037833100"
                      normalised: "037833100"
                      valid: true
                      issuer: "037833"
                      issue: "10"
                      check_digit: "0"
                      reason: null
                      standard: ANSI X9.6 (CUSIP mod-10 double-add-double)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ANSI X9.6
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                "037833101":
                  summary: "037833101"
                  value:
                    dataset: util-cusip
                    key: "037833101"
                    data:
                      input: "037833101"
                      normalised: "037833101"
                      valid: false
                      issuer: "037833"
                      issue: "10"
                      check_digit: "1"
                      reason: Check digit does not validate (expected 0).
                      standard: ANSI X9.6 (CUSIP mod-10 double-add-double)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ANSI X9.6
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-sedol/{key}:
    get:
      tags:
        - utilities
      summary: SEDOL validation — 7-character LSE identifier, weighted mod-10 check digit
      operationId: getUtilSedol
      description: "Standard: LSE SEDOL. Pure deterministic computation — never cached, never stale.
        Malformed keys are rejected with 400 before any payment is taken; a well-formed key that
        validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `0263494`"
          schema:
            type: string
            example: "0263494"
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-sedol
                      data:
                        $ref: "#/components/schemas/UtilSedolData"
                      deterministic:
                        type: boolean
              examples:
                "0263494":
                  summary: "0263494"
                  value:
                    dataset: util-sedol
                    key: "0263494"
                    data:
                      input: "0263494"
                      normalised: "0263494"
                      valid: true
                      reason: null
                      standard: London Stock Exchange SEDOL (weighted mod-10)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: LSE SEDOL
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                "0263495":
                  summary: "0263495"
                  value:
                    dataset: util-sedol
                    key: "0263495"
                    data:
                      input: "0263495"
                      normalised: "0263495"
                      valid: false
                      reason: Check digit does not validate (weighted sum not divisible by 10).
                      standard: London Stock Exchange SEDOL (weighted mod-10)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: LSE SEDOL
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-lei/{key}:
    get:
      tags:
        - utilities
      summary: LEI validation — 20-character Legal Entity Identifier, MOD 97-10 check digits
      operationId: getUtilLei
      description: "Standard: ISO 17442. Pure deterministic computation — never cached, never stale.
        Malformed keys are rejected with 400 before any payment is taken; a well-formed key that
        validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `529900T8BM49AURSDO55`"
          schema:
            type: string
            example: 529900T8BM49AURSDO55
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-lei
                      data:
                        $ref: "#/components/schemas/UtilLeiData"
                      deterministic:
                        type: boolean
              examples:
                529900T8BM49AURSDO55:
                  summary: 529900T8BM49AURSDO55
                  value:
                    dataset: util-lei
                    key: 529900T8BM49AURSDO55
                    data:
                      input: 529900T8BM49AURSDO55
                      normalised: 529900T8BM49AURSDO55
                      valid: true
                      lou_prefix: "5299"
                      check_digits: "55"
                      reason: null
                      standard: ISO 17442 (MOD 97-10 per ISO 7064)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 17442
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                529900T8BM49AURSDO56:
                  summary: 529900T8BM49AURSDO56
                  value:
                    dataset: util-lei
                    key: 529900T8BM49AURSDO56
                    data:
                      input: 529900T8BM49AURSDO56
                      normalised: 529900T8BM49AURSDO56
                      valid: false
                      lou_prefix: "5299"
                      check_digits: "56"
                      reason: Check digits do not validate (MOD 97-10 remainder is not 1).
                      standard: ISO 17442 (MOD 97-10 per ISO 7064)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 17442
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-card/{key}:
    get:
      tags:
        - utilities
      summary: Payment card number Luhn validation and network detection by public prefix/length rules
        (not an issuer BIN lookup)
      operationId: getUtilCard
      description: "Standard: ISO/IEC 7812 (Luhn) + public network range rules. Pure deterministic
        computation — never cached, never stale. Malformed keys are rejected with 400 before any
        payment is taken; a well-formed key that validates to `valid: false` is a legitimate paid
        answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `4111111111111111`"
          schema:
            type: string
            example: "4111111111111111"
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-card
                      data:
                        $ref: "#/components/schemas/UtilCardData"
                      deterministic:
                        type: boolean
              examples:
                "4111111111111111":
                  summary: "4111111111111111"
                  value:
                    dataset: util-card
                    key: "4111111111111111"
                    data:
                      input: "4111111111111111"
                      normalised: "4111111111111111"
                      luhn_valid: true
                      network: Visa
                      length: 16
                      reason: null
                      standard: ISO/IEC 7812 (Luhn) + public network prefix/length rules
                      caveat: Network detection uses public prefix range rules, not an issuer (BIN) database.
                        Structural/check-digit validation only — confirms the identifier is
                        well-formed, not that it exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO/IEC 7812 (Luhn) + public network range rules
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                "4111111111111112":
                  summary: "4111111111111112"
                  value:
                    dataset: util-card
                    key: "4111111111111112"
                    data:
                      input: "4111111111111112"
                      normalised: "4111111111111112"
                      luhn_valid: false
                      network: Visa
                      length: 16
                      reason: Luhn check digit does not validate.
                      standard: ISO/IEC 7812 (Luhn) + public network prefix/length rules
                      caveat: Network detection uses public prefix range rules, not an issuer (BIN) database.
                        Structural/check-digit validation only — confirms the identifier is
                        well-formed, not that it exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO/IEC 7812 (Luhn) + public network range rules
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-aba-rtn/{key}:
    get:
      tags:
        - utilities
      summary: US ABA routing transit number validation — 3-7-1 weighted mod-10 check digit
      operationId: getUtilAbaRtn
      description: "Standard: ABA routing number scheme. Pure deterministic computation — never cached,
        never stale. Malformed keys are rejected with 400 before any payment is taken; a well-formed
        key that validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `011000015`"
          schema:
            type: string
            example: "011000015"
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-aba-rtn
                      data:
                        $ref: "#/components/schemas/UtilAbaRtnData"
                      deterministic:
                        type: boolean
              examples:
                "011000015":
                  summary: "011000015"
                  value:
                    dataset: util-aba-rtn
                    key: "011000015"
                    data:
                      input: "011000015"
                      normalised: "011000015"
                      valid: true
                      federal_reserve_district: "1"
                      reason: null
                      standard: ABA routing number (3-7-1 weighted mod-10)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ABA routing number scheme
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                "011000016":
                  summary: "011000016"
                  value:
                    dataset: util-aba-rtn
                    key: "011000016"
                    data:
                      input: "011000016"
                      normalised: "011000016"
                      valid: false
                      federal_reserve_district: null
                      reason: Check digit does not validate (3-7-1 weighted sum not divisible by 10).
                      standard: ABA routing number (3-7-1 weighted mod-10)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        exists or is active.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ABA routing number scheme
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-gtin/{key}:
    get:
      tags:
        - utilities
      summary: GTIN-8/12/13/14 (EAN/UPC) validation, plus 'compute:<digits>' check-digit calculation
      operationId: getUtilGtin
      description: "Standard: GS1 General Specifications (mod-10). Pure deterministic computation — never
        cached, never stale. Malformed keys are rejected with 400 before any payment is taken; a
        well-formed key that validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `5000112637922`"
          schema:
            type: string
            example: "5000112637922"
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-gtin
                      data:
                        $ref: "#/components/schemas/UtilGtinData"
                      deterministic:
                        type: boolean
              examples:
                "5000112637922":
                  summary: "5000112637922"
                  value:
                    dataset: util-gtin
                    key: "5000112637922"
                    data:
                      input: "5000112637922"
                      normalised: "5000112637922"
                      valid: true
                      type: GTIN-13 (EAN-13)
                      check_digit: 2
                      reason: null
                      standard: GS1 General Specifications (mod-10)
                      caveat: Structural/check-digit validation only — confirms the code is well-formed, not that it is
                        assigned to a real product. A GS1 prefix identifies the GS1 member
                        organisation that issued the number, NOT the country of manufacture.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: GS1 General Specifications (mod-10)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                compute_400638133393:
                  summary: compute:400638133393
                  value:
                    dataset: util-gtin
                    key: compute:400638133393
                    data:
                      input: compute:400638133393
                      mode: compute
                      partial: "400638133393"
                      check_digit: 1
                      full_code: "4006381333931"
                      type: GTIN-13 (EAN-13)
                      standard: GS1 General Specifications (mod-10)
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: GS1 General Specifications (mod-10)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-isbn/{key}:
    get:
      tags:
        - utilities
      summary: ISBN-10/ISBN-13 validation with bidirectional conversion
      operationId: getUtilIsbn
      description: "Standard: ISO 2108. Pure deterministic computation — never cached, never stale.
        Malformed keys are rejected with 400 before any payment is taken; a well-formed key that
        validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `9780306406157`"
          schema:
            type: string
            example: "9780306406157"
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-isbn
                      data:
                        $ref: "#/components/schemas/UtilIsbnData"
                      deterministic:
                        type: boolean
              examples:
                "9780306406157":
                  summary: "9780306406157"
                  value:
                    dataset: util-isbn
                    key: "9780306406157"
                    data:
                      input: "9780306406157"
                      normalised: "9780306406157"
                      valid: true
                      format: ISBN-13
                      isbn10: "0306406152"
                      isbn13: "9780306406157"
                      reason: null
                      standard: ISO 2108 (ISBN-10 mod-11 / ISBN-13 GS1 mod-10)
                      caveat: Structural/check-digit validation only — confirms the code is well-formed, not that it is
                        assigned to a real product.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 2108
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                "0306406152":
                  summary: "0306406152"
                  value:
                    dataset: util-isbn
                    key: "0306406152"
                    data:
                      input: "0306406152"
                      normalised: "0306406152"
                      valid: true
                      format: ISBN-10
                      isbn10: "0306406152"
                      isbn13: "9780306406157"
                      reason: null
                      standard: ISO 2108 (ISBN-10 mod-11 / ISBN-13 GS1 mod-10)
                      caveat: Structural/check-digit validation only — confirms the code is well-formed, not that it is
                        assigned to a real product.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 2108
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-issn/{key}:
    get:
      tags:
        - utilities
      summary: ISSN validation — 8-character serial identifier, weighted mod-11 check character
      operationId: getUtilIssn
      description: "Standard: ISO 3297. Pure deterministic computation — never cached, never stale.
        Malformed keys are rejected with 400 before any payment is taken; a well-formed key that
        validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `0317-8471`"
          schema:
            type: string
            example: 0317-8471
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-issn
                      data:
                        $ref: "#/components/schemas/UtilIssnData"
                      deterministic:
                        type: boolean
              examples:
                0317-8471:
                  summary: 0317-8471
                  value:
                    dataset: util-issn
                    key: 0317-8471
                    data:
                      input: 0317-8471
                      normalised: 0317-8471
                      valid: true
                      reason: null
                      standard: ISO 3297 (weighted mod-11)
                      caveat: Structural/check-digit validation only — confirms the code is well-formed, not that it is
                        assigned to a real product.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 3297
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                0317-8472:
                  summary: 0317-8472
                  value:
                    dataset: util-issn
                    key: 0317-8472
                    data:
                      input: 0317-8472
                      normalised: 0317-8472
                      valid: false
                      reason: Check character does not validate (expected 1).
                      standard: ISO 3297 (weighted mod-11)
                      caveat: Structural/check-digit validation only — confirms the code is well-formed, not that it is
                        assigned to a real product.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 3297
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-container/{key}:
    get:
      tags:
        - utilities
      summary: ISO 6346 shipping container number validation and parse — owner code, equipment category,
        serial, check digit
      operationId: getUtilContainer
      description: "Standard: ISO 6346. Pure deterministic computation — never cached, never stale.
        Malformed keys are rejected with 400 before any payment is taken; a well-formed key that
        validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `CSQU3054383`"
          schema:
            type: string
            example: CSQU3054383
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-container
                      data:
                        $ref: "#/components/schemas/UtilContainerData"
                      deterministic:
                        type: boolean
              examples:
                CSQU3054383:
                  summary: CSQU3054383
                  value:
                    dataset: util-container
                    key: CSQU3054383
                    data:
                      input: CSQU3054383
                      normalised: CSQU3054383
                      valid: true
                      owner_code: CSQ
                      equipment_category: U
                      equipment_category_meaning: freight container
                      serial: "305438"
                      check_digit: 3
                      reason: null
                      standard: ISO 6346 (weighted mod-11)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        is registered or in service. Owner codes are registered with the BIC; this
                        endpoint does not look up the owner.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 6346
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                CSQU3054384:
                  summary: CSQU3054384
                  value:
                    dataset: util-container
                    key: CSQU3054384
                    data:
                      input: CSQU3054384
                      normalised: CSQU3054384
                      valid: false
                      owner_code: CSQ
                      equipment_category: U
                      equipment_category_meaning: freight container
                      serial: "305438"
                      check_digit: 4
                      reason: Check digit does not validate (expected 3).
                      standard: ISO 6346 (weighted mod-11)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        is registered or in service. Owner codes are registered with the BIC; this
                        endpoint does not look up the owner.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: ISO 6346
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-imo/{key}:
    get:
      tags:
        - utilities
      summary: IMO ship identification number validation — 7-digit weighted check digit
      operationId: getUtilImo
      description: "Standard: IMO ship identification number scheme. Pure deterministic computation —
        never cached, never stale. Malformed keys are rejected with 400 before any payment is taken;
        a well-formed key that validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `9074729`"
          schema:
            type: string
            example: "9074729"
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-imo
                      data:
                        $ref: "#/components/schemas/UtilImoData"
                      deterministic:
                        type: boolean
              examples:
                "9074720":
                  summary: "9074720"
                  value:
                    dataset: util-imo
                    key: "9074720"
                    data:
                      input: "9074720"
                      normalised: IMO 9074720
                      valid: false
                      reason: Check digit does not validate (expected 9).
                      standard: IMO ship identification number scheme (weighted mod-10)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        is registered or in service.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: IMO ship identification number scheme
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                "9074729":
                  summary: "9074729"
                  value:
                    dataset: util-imo
                    key: "9074729"
                    data:
                      input: "9074729"
                      normalised: IMO 9074729
                      valid: true
                      reason: null
                      standard: IMO ship identification number scheme (weighted mod-10)
                      caveat: Structural/check-digit validation only — confirms the identifier is well-formed, not that it
                        is registered or in service.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: IMO ship identification number scheme
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-checkdigit/{key}:
    get:
      tags:
        - utilities
      summary: "Generic check-digit service:
        '<luhn|verhoeff|damm|mod97-10|mod11-2>:<verify|compute>:<digits>'"
      operationId: getUtilCheckdigit
      description: "Standard: Luhn / Verhoeff / Damm / ISO 7064 (MOD 97-10, MOD 11-2). Pure deterministic
        computation — never cached, never stale. Malformed keys are rejected with 400 before any
        payment is taken; a well-formed key that validates to `valid: false` is a legitimate paid
        answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `luhn:verify:79927398713`"
          schema:
            type: string
            example: luhn:verify:79927398713
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-checkdigit
                      data:
                        $ref: "#/components/schemas/UtilCheckdigitData"
                      deterministic:
                        type: boolean
              examples:
                luhn_verify_79927398713:
                  summary: luhn:verify:79927398713
                  value:
                    dataset: util-checkdigit
                    key: luhn:verify:79927398713
                    data:
                      algorithm: luhn
                      mode: verify
                      input: "79927398713"
                      valid: true
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: Luhn / Verhoeff / Damm / ISO 7064 (MOD 97-10, MOD 11-2)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                damm_compute_572:
                  summary: damm:compute:572
                  value:
                    dataset: util-checkdigit
                    key: damm:compute:572
                    data:
                      algorithm: damm
                      mode: compute
                      input: "572"
                      check_digit: 4
                      full_value: "5724"
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: Luhn / Verhoeff / Damm / ISO 7064 (MOD 97-10, MOD 11-2)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-geo/{key}:
    get:
      tags:
        - utilities
      summary: "Great-circle math: 'distance:lat1,lon1,lat2,lon2' (km/mi/nm + bearing) and
        'destination:lat,lon,bearing,km'"
      operationId: getUtilGeo
      description: "Standard: Haversine, spherical earth (mean radius 6371.0088 km). Pure deterministic
        computation — never cached, never stale. Malformed keys are rejected with 400 before any
        payment is taken; a well-formed key that validates to `valid: false` is a legitimate paid
        answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `distance:51.5074,-0.1278,48.8566,2.3522`"
          schema:
            type: string
            example: distance:51.5074,-0.1278,48.8566,2.3522
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-geo
                      data:
                        $ref: "#/components/schemas/UtilGeoData"
                      deterministic:
                        type: boolean
              examples:
                distance_51.5074_-0.1278_48.8566_2.3522:
                  summary: distance:51.5074,-0.1278,48.8566,2.3522
                  value:
                    dataset: util-geo
                    key: distance:51.5074,-0.1278,48.8566,2.3522
                    data:
                      from:
                        lat: 51.5074
                        lon: -0.1278
                      to:
                        lat: 48.8566
                        lon: 2.3522
                      distance_km: 343.557
                      distance_miles: 213.476
                      distance_nautical_miles: 185.506
                      initial_bearing_degrees: 148.12
                      method: haversine, spherical earth, mean radius 6371.0088 km
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: Haversine, spherical earth (mean radius 6371.0088 km)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                destination_51.5074_-0.1278_90_100:
                  summary: destination:51.5074,-0.1278,90,100
                  value:
                    dataset: util-geo
                    key: destination:51.5074,-0.1278,90,100
                    data:
                      from:
                        lat: 51.5074
                        lon: -0.1278
                      bearing_degrees: 90
                      distance_km: 100
                      destination:
                        lat: 51.498526
                        lon: 1.316904
                      method: spherical earth, mean radius 6371.0088 km
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: Haversine, spherical earth (mean radius 6371.0088 km)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-geohash/{key}:
    get:
      tags:
        - utilities
      summary: "Geohash utilities: 'encode:lat,lon[,precision]' and 'decode:<hash>' with bounding box"
      operationId: getUtilGeohash
      description: "Standard: Geohash (public domain, Niemeyer 2008). Pure deterministic computation —
        never cached, never stale. Malformed keys are rejected with 400 before any payment is taken;
        a well-formed key that validates to `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `encode:51.5074,-0.1278,9`"
          schema:
            type: string
            example: encode:51.5074,-0.1278,9
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-geohash
                      data:
                        $ref: "#/components/schemas/UtilGeohashData"
                      deterministic:
                        type: boolean
              examples:
                encode_51.5074_-0.1278_9:
                  summary: encode:51.5074,-0.1278,9
                  value:
                    dataset: util-geohash
                    key: encode:51.5074,-0.1278,9
                    data:
                      lat: 51.5074
                      lon: -0.1278
                      precision: 9
                      geohash: gcpvj0duq
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: Geohash (public domain, Niemeyer 2008)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
                decode_gcpvj0:
                  summary: decode:gcpvj0
                  value:
                    dataset: util-geohash
                    key: decode:gcpvj0
                    data:
                      geohash: gcpvj0
                      lat: 51.506653
                      lon: -0.126343
                      bounds:
                        lat_min: 51.50390625
                        lat_max: 51.5093994140625
                        lon_min: -0.1318359375
                        lon_max: -0.120849609375
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: Geohash (public domain, Niemeyer 2008)
                    ttl_seconds: 315360000
                    stale: false
                    deterministic: true
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-oui/{key}:
    get:
      tags:
        - utilities
      summary: MAC address vendor (OUI) lookup — accepts a full MAC or prefix, e.g. '00:00:5E' or
        '00005E005300'; flags locally-administered/randomised addresses
      operationId: getUtilOui
      description: "Standard: IEEE OUI registry (MA-L). Bundled snapshot lookup (source: Wireshark manuf
        database (IEEE-derived), via npm oui-data; refreshed roughly every 30 days). Malformed keys
        are rejected with 400 before any payment is taken; a well-formed key that validates to
        `valid: false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `00:00:5E:00:53:00`"
          schema:
            type: string
            example: 00:00:5E:00:53:00
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-oui
                      data:
                        $ref: "#/components/schemas/UtilOuiData"
                      deterministic:
                        type: boolean
              examples:
                00_00_5E_00_53_00:
                  summary: 00:00:5E:00:53:00
                  value:
                    dataset: util-oui
                    key: 00:00:5E:00:53:00
                    data:
                      input: 00:00:5E:00:53:00
                      oui: 00:00:5E
                      found: true
                      locally_administered: false
                      multicast: false
                      data_generated_at: 2026-07-05T14:56:17.807Z
                      vendor: ICANN, IANA Department
                      vendor_country: United States
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: Wireshark manuf database (IEEE-derived), via npm oui-data
                    ttl_seconds: 2592000
                    stale: false
                    deterministic: false
                02_00_00_00_00_01:
                  summary: 02:00:00:00:00:01
                  value:
                    dataset: util-oui
                    key: 02:00:00:00:00:01
                    data:
                      input: 02:00:00:00:00:01
                      oui: 02:00:00
                      found: false
                      locally_administered: true
                      multicast: false
                      data_generated_at: 2026-07-05T14:56:17.807Z
                      caveat: The locally-administered bit is set — this address was assigned by software (e.g. MAC
                        randomisation), so any registry match is coincidental.
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: Wireshark manuf database (IEEE-derived), via npm oui-data
                    ttl_seconds: 2592000
                    stale: false
                    deterministic: false
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-airport/{key}:
    get:
      tags:
        - utilities
      summary: Airport lookup by IATA or ICAO/ident code — 'LHR', 'EGLL', 'iata:LHR', 'icao:EGLL'; name,
        coordinates, elevation, country, scheduled service
      operationId: getUtilAirport
      description: "Standard: IATA 3-letter / ICAO 4-letter airport codes. Bundled snapshot lookup
        (source: OurAirports (public domain); refreshed roughly every 30 days). Malformed keys are
        rejected with 400 before any payment is taken; a well-formed key that validates to `valid:
        false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `LHR`"
          schema:
            type: string
            example: LHR
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-airport
                      data:
                        $ref: "#/components/schemas/UtilAirportData"
                      deterministic:
                        type: boolean
              examples:
                LHR:
                  summary: LHR
                  value:
                    dataset: util-airport
                    key: LHR
                    data:
                      input: LHR
                      lookup: iata
                      code: LHR
                      found: true
                      airport:
                        ident: EGLL
                        type: large_airport
                        name: London Heathrow Airport
                        latitude: 51.47075
                        longitude: -0.45991
                        elevation_ft: 83
                        iso_country: GB
                        iso_region: GB-ENG
                        municipality: London
                        scheduled_service: true
                        icao: EGLL
                        iata: LHR
                      data_generated_at: 2026-07-05T14:56:18.308Z
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: OurAirports (public domain)
                    ttl_seconds: 2592000
                    stale: false
                    deterministic: false
                icao_EGLL:
                  summary: icao:EGLL
                  value:
                    dataset: util-airport
                    key: icao:EGLL
                    data:
                      input: icao:EGLL
                      lookup: icao/ident
                      code: EGLL
                      found: true
                      airport:
                        ident: EGLL
                        type: large_airport
                        name: London Heathrow Airport
                        latitude: 51.47075
                        longitude: -0.45991
                        elevation_ft: 83
                        iso_country: GB
                        iso_region: GB-ENG
                        municipality: London
                        scheduled_service: true
                        icao: EGLL
                        iata: LHR
                      data_generated_at: 2026-07-05T14:56:18.308Z
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: OurAirports (public domain)
                    ttl_seconds: 2592000
                    stale: false
                    deterministic: false
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-tz/{key}:
    get:
      tags:
        - utilities
      summary: IANA timezone info — 'zone:Europe/London[:2026-01-15]' (UTC offset, DST status,
        abbreviation) or 'country:GB' (zone list)
      operationId: getUtilTz
      description: "Standard: IANA tzdb; offsets from runtime ICU. Bundled snapshot lookup (source: IANA
        tzdb zone1970.tab + Node ICU tzdata; refreshed roughly every 90 days). Malformed keys are
        rejected with 400 before any payment is taken; a well-formed key that validates to `valid:
        false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `zone:Europe/London`"
          schema:
            type: string
            example: zone:Europe/London
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-tz
                      data:
                        $ref: "#/components/schemas/UtilTzData"
                      deterministic:
                        type: boolean
              examples:
                zone_Europe_London:
                  summary: zone:Europe/London
                  value:
                    dataset: util-tz
                    key: zone:Europe/London
                    data:
                      input: zone:Europe/London
                      zone: Europe/London
                      canonical_zone: Europe/London
                      valid: true
                      at: 2026-07-05T15:19:48.393Z
                      utc_offset: +01:00
                      utc_offset_minutes: 60
                      abbreviation: GMT+1
                      observes_dst: true
                      is_dst: true
                      standard_offset: +00:00
                      countries:
                        - GB
                        - GG
                        - IM
                        - JE
                      coordinates: +513030-0000731
                      note: Offsets computed by the runtime ICU tzdata; country mapping from the bundled zone1970.tab
                        snapshot.
                      data_generated_at: 2026-07-05T14:56:18.410Z
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: IANA tzdb zone1970.tab + Node ICU tzdata
                    ttl_seconds: 7776000
                    stale: false
                    deterministic: false
                country_GB:
                  summary: country:GB
                  value:
                    dataset: util-tz
                    key: country:GB
                    data:
                      input: country:GB
                      country: GB
                      found: true
                      zones:
                        - Europe/London
                      data_generated_at: 2026-07-05T14:56:18.410Z
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: IANA tzdb zone1970.tab + Node ICU tzdata
                    ttl_seconds: 7776000
                    stale: false
                    deterministic: false
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-currency/{key}:
    get:
      tags:
        - utilities
      summary: ISO 4217 currency lookup by alpha or numeric code — 'GBP' or '826'; name, minor units,
        using entities, withdrawn-code history
      operationId: getUtilCurrency
      description: "Standard: ISO 4217. Bundled snapshot lookup (source: datasets/currency-codes (ISO 4217
        published list); refreshed roughly every 90 days). Malformed keys are rejected with 400
        before any payment is taken; a well-formed key that validates to `valid: false` is a
        legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `GBP`"
          schema:
            type: string
            example: GBP
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-currency
                      data:
                        $ref: "#/components/schemas/UtilCurrencyData"
                      deterministic:
                        type: boolean
              examples:
                "826":
                  summary: "826"
                  value:
                    dataset: util-currency
                    key: "826"
                    data:
                      input: "826"
                      code: GBP
                      found: true
                      status: active
                      name: Pound Sterling
                      numeric_code: "826"
                      minor_units: 2
                      entities: &a1
                        - GUERNSEY
                        - ISLE OF MAN
                        - JERSEY
                        - UNITED KINGDOM OF GREAT BRITAIN AND NORTHERN IRELAND (THE)
                      data_generated_at: 2026-07-05T14:56:18.395Z
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: datasets/currency-codes (ISO 4217 published list)
                    ttl_seconds: 7776000
                    stale: false
                    deterministic: false
                GBP:
                  summary: GBP
                  value:
                    dataset: util-currency
                    key: GBP
                    data:
                      input: GBP
                      code: GBP
                      found: true
                      status: active
                      name: Pound Sterling
                      numeric_code: "826"
                      minor_units: 2
                      entities: *a1
                      data_generated_at: 2026-07-05T14:56:18.395Z
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: datasets/currency-codes (ISO 4217 published list)
                    ttl_seconds: 7776000
                    stale: false
                    deterministic: false
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/util-locode/{key}:
    get:
      tags:
        - utilities
      summary: UN/LOCODE lookup — 'GBLON' or 'GB:LON'; place name, subdivision, decoded function
        classifiers (port/rail/road/airport…), status, coordinates
      operationId: getUtilLocode
      description: "Standard: UNECE Recommendation 16 (UN/LOCODE). Bundled snapshot lookup (source: UNECE
        UN/LOCODE via datasets/un-locode; refreshed roughly every 180 days). Malformed keys are
        rejected with 400 before any payment is taken; a well-formed key that validates to `valid:
        false` is a legitimate paid answer."
      parameters:
        - name: key
          in: path
          required: true
          description: "See summary for the key format. Example: `GBLON`"
          schema:
            type: string
            example: GBLON
        - $ref: "#/components/parameters/PaymentSignature"
      responses:
        "200":
          description: Success — payment settled.
          headers:
            PAYMENT-RESPONSE:
              $ref: "#/components/headers/PaymentResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ResponseEnvelope"
                  - type: object
                    properties:
                      dataset:
                        type: string
                        enum:
                          - util-locode
                      data:
                        $ref: "#/components/schemas/UtilLocodeData"
                      deterministic:
                        type: boolean
              examples:
                GBLON:
                  summary: GBLON
                  value:
                    dataset: util-locode
                    key: GBLON
                    data:
                      input: GBLON
                      locode: GBLON
                      found: true
                      entry:
                        locode: GBLON
                        country: GB
                        location: LON
                        name: London
                        subdivision: LND
                        status: AF
                        status_meaning: approved by national facilitation body
                        functions:
                          - code: "1"
                            meaning: port (maritime)
                          - code: "5"
                            meaning: postal exchange office
                        function_raw: 1---5---
                        latitude: null
                        longitude: null
                        iata: null
                      data_generated_at: 2026-07-05T14:56:18.601Z
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: UNECE UN/LOCODE via datasets/un-locode
                    ttl_seconds: 15552000
                    stale: false
                    deterministic: false
                GB_LON:
                  summary: GB:LON
                  value:
                    dataset: util-locode
                    key: GB:LON
                    data:
                      input: GB:LON
                      locode: GBLON
                      found: true
                      entry:
                        locode: GBLON
                        country: GB
                        location: LON
                        name: London
                        subdivision: LND
                        status: AF
                        status_meaning: approved by national facilitation body
                        functions:
                          - code: "1"
                            meaning: port (maritime)
                          - code: "5"
                            meaning: postal exchange office
                        function_raw: 1---5---
                        latitude: null
                        longitude: null
                        iata: null
                      data_generated_at: 2026-07-05T14:56:18.601Z
                    fetched_at: 2026-01-01T00:00:00.000Z
                    fetch_status: ok
                    source: UNECE UN/LOCODE via datasets/un-locode
                    ttl_seconds: 15552000
                    stale: false
                    deterministic: false
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "500":
          $ref: "#/components/responses/InternalError"
components:
  parameters:
    PaymentSignature:
      name: PAYMENT-SIGNATURE
      in: header
      required: false
      description: "Signed x402 payment payload. Omit on the first request to receive the 402 challenge;
        attach on retry. Legacy alias: X-PAYMENT."
      schema:
        type: string
  headers:
    PaymentResponse:
      description: Base64-encoded settlement receipt (also mirrored as X-PAYMENT-RESPONSE).
      schema:
        type: string
  responses:
    PaymentRequired:
      description: No valid payment attached, or the attached payment failed verification/settlement. The
        PAYMENT-REQUIRED header and body describe the exact amount, network, asset and payee — treat
        as the source of truth for price.
      headers:
        PAYMENT-REQUIRED:
          description: Base64-encoded payment requirements (x402 v2).
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentRequiredBody"
    InvalidRequest:
      description: INVALID_REQUEST — key is malformed. No payment taken.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    EntityNotFound:
      description: ENTITY_NOT_FOUND — final, non-retryable result. No record exists for this input.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    BucketNotSeeded:
      description: BUCKET_NOT_SEEDED — key is well-formed but the daily pipeline has not populated this
        segment yet. Retryable later. Payment has already settled (settle-before-serve).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    IngestInProgress:
      description: INGEST_IN_PROGRESS — first-ever lookup did not complete in time. Retry after
        retry_after_seconds.
      headers:
        Retry-After:
          schema:
            type: string
            example: "5"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: INTERNAL_ERROR — genuine infrastructure failure, not a payment or input problem. Retryable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    ResponseEnvelope:
      type: object
      description: Common shape wrapping every successful paid response, regardless of dataset.
      properties:
        dataset:
          type: string
        key:
          type: string
        data: {}
        fetched_at:
          type: string
          format: date-time
        fetch_status:
          type: string
          enum:
            - ok
            - error
            - partial
        source:
          type: string
        ttl_seconds:
          type: integer
        stale:
          type: boolean
      required:
        - dataset
        - key
        - data
        - fetched_at
        - fetch_status
        - source
        - ttl_seconds
        - stale
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - PAYMENT_INVALID
                - PAYMENT_SETTLEMENT_FAILED
                - INVALID_REQUEST
                - UNKNOWN_DATASET
                - DATASET_DISABLED
                - ENTITY_NOT_FOUND
                - BUCKET_NOT_SEEDED
                - INGEST_UNAVAILABLE
                - INGEST_IN_PROGRESS
                - INTERNAL_ERROR
              description: Stable machine-readable code. Branch on this, never on message text.
            message:
              type: string
            retryable:
              type: boolean
              description: Whether the SAME request, retried later, has a reasonable chance of succeeding. Back
                off, and honor retry_after_seconds when present.
            retry_after_seconds:
              type: integer
            docs_url:
              type: string
              format: uri
          required:
            - code
            - message
            - retryable
            - docs_url
      required:
        - error
    PaymentRequiredBody:
      type: object
      description: x402 v2 payment challenge.
      properties:
        x402Version:
          type: integer
          example: 2
        error:
          type: string
          example: Payment required
        resource:
          type: object
          properties:
            url:
              type: string
            description:
              type: string
            mimeType:
              type: string
        accepts:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
                enum:
                  - exact
                  - upto
              network:
                type: string
                example: eip155:8453
              amount:
                type: string
                description: Atomic units of the asset.
              asset:
                type: string
                description: Token contract address (USDC).
              payTo:
                type: string
                description: Recipient wallet address.
              maxTimeoutSeconds:
                type: integer
              extra:
                type: object
                description: EIP-712 domain for the asset — NOT dataset metadata.
                properties:
                  name:
                    type: string
                    example: USD Coin
                  version:
                    type: string
                    example: "2"
    MetaResponse:
      type: object
      description: Freshness info only — no data payload, no payment required.
      properties:
        dataset:
          type: string
        key:
          type: string
        fetched_at:
          type: string
          format: date-time
        fetch_status:
          type: string
          enum:
            - ok
            - error
            - partial
            - not_found
        source:
          type: string
        ttl_seconds:
          type: integer
        stale:
          type: boolean
    MotHistoryData:
      type: object
      description: Run capture-fixtures.ts to infer this shape.
    ReliabilityData:
      type: object
      description: Run capture-fixtures.ts against a seeded 'reliability' bucket.
    MileageData:
      type: object
      description: Run capture-fixtures.ts against a seeded 'mileage' bucket.
    ParcData:
      type: object
      description: Run capture-fixtures.ts against a seeded 'parc' bucket.
    FuelmixData:
      type: object
      description: Run capture-fixtures.ts against a seeded 'fuelmix' bucket.
    ColourData:
      type: object
      description: Run capture-fixtures.ts against a seeded 'colour' bucket.
    TemporalData:
      type: object
      description: Run capture-fixtures.ts against a seeded 'temporal' bucket.
    AnalyticsData:
      oneOf:
        - $ref: "#/components/schemas/ReliabilityData"
        - $ref: "#/components/schemas/MileageData"
        - $ref: "#/components/schemas/ParcData"
        - $ref: "#/components/schemas/FuelmixData"
        - $ref: "#/components/schemas/ColourData"
        - $ref: "#/components/schemas/TemporalData"
      discriminator:
        propertyName: family
        mapping:
          reliability: "#/components/schemas/ReliabilityData"
          mileage: "#/components/schemas/MileageData"
          parc: "#/components/schemas/ParcData"
          fuelmix: "#/components/schemas/FuelmixData"
          colour: "#/components/schemas/ColourData"
          temporal: "#/components/schemas/TemporalData"
    UtilVinData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        structurally_valid:
          type: boolean
        check_digit_valid:
          type: boolean
        wmi:
          type: string
        wmi_region:
          type: string
        manufacturer:
          type: string
        vds:
          type: string
        vis:
          type: string
        model_year_code:
          type: string
        model_year_candidates:
          type: array
          items:
            type: integer
        plant_code:
          type: string
        reason:
          type: "null"
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - structurally_valid
        - check_digit_valid
        - wmi
        - wmi_region
        - manufacturer
        - vds
        - vis
        - model_year_code
        - model_year_candidates
        - plant_code
        - reason
        - standard
        - caveat
    UtilUkPlateData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        format:
          type: string
        area_code:
          type:
            - string
            - "null"
        age_identifier:
          type:
            - string
            - "null"
        registration_period:
          type:
            - string
            - "null"
        notes:
          type:
            - "null"
            - string
        reason:
          type: "null"
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - format
        - area_code
        - age_identifier
        - registration_period
        - notes
        - reason
        - standard
        - caveat
    UtilMotDueData:
      type: object
      properties:
        input:
          type: string
        first_registered:
          type: string
        first_mot_due:
          type: string
        first_mot_now_due:
          type: boolean
        vehicle_age_years:
          type: integer
        historic_exemption_possible:
          type: boolean
        reason:
          type: "null"
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - first_registered
        - first_mot_due
        - first_mot_now_due
        - vehicle_age_years
        - historic_exemption_possible
        - reason
        - standard
        - caveat
    UtilTyreSizeData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        section_width_mm:
          type:
            - integer
            - "null"
        aspect_ratio_percent:
          type:
            - integer
            - "null"
        construction:
          type:
            - string
            - "null"
        rim_diameter_inches:
          type:
            - integer
            - "null"
        overall_diameter_mm:
          type:
            - integer
            - "null"
        load_index:
          type:
            - integer
            - "null"
        max_load_kg:
          type:
            - integer
            - "null"
        speed_rating:
          type:
            - string
            - "null"
        max_speed_kmh:
          type:
            - integer
            - "null"
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - section_width_mm
        - aspect_ratio_percent
        - construction
        - rim_diameter_inches
        - overall_diameter_mm
        - load_index
        - max_load_kg
        - speed_rating
        - max_speed_kmh
        - reason
        - standard
        - caveat
    UtilIbanData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        country:
          type: string
        check_digits:
          type: string
        bban:
          type: string
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - country
        - check_digits
        - bban
        - reason
        - standard
        - caveat
    UtilIsinData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        country:
          type: string
        nsin:
          type: string
        check_digit:
          type: string
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - country
        - nsin
        - check_digit
        - reason
        - standard
        - caveat
    UtilCusipData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        issuer:
          type: string
        issue:
          type: string
        check_digit:
          type: string
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - issuer
        - issue
        - check_digit
        - reason
        - standard
        - caveat
    UtilSedolData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - reason
        - standard
        - caveat
    UtilLeiData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        lou_prefix:
          type: string
        check_digits:
          type: string
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - lou_prefix
        - check_digits
        - reason
        - standard
        - caveat
    UtilCardData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        luhn_valid:
          type: boolean
        network:
          type: string
        length:
          type: integer
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - luhn_valid
        - network
        - length
        - reason
        - standard
        - caveat
    UtilAbaRtnData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        federal_reserve_district:
          type:
            - string
            - "null"
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - federal_reserve_district
        - reason
        - standard
        - caveat
    UtilGtinData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        type:
          type: string
        check_digit:
          type: integer
        reason:
          type: "null"
        standard:
          type: string
        caveat:
          type: string
        mode:
          type: string
        partial:
          type: string
        full_code:
          type: string
      required:
        - input
        - check_digit
        - type
        - standard
    UtilIsbnData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        format:
          type: string
        isbn10:
          type: string
        isbn13:
          type: string
        reason:
          type: "null"
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - format
        - isbn10
        - isbn13
        - reason
        - standard
        - caveat
    UtilIssnData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - reason
        - standard
        - caveat
    UtilContainerData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        owner_code:
          type: string
        equipment_category:
          type: string
        equipment_category_meaning:
          type: string
        serial:
          type: string
        check_digit:
          type: integer
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - owner_code
        - equipment_category
        - equipment_category_meaning
        - serial
        - check_digit
        - reason
        - standard
        - caveat
    UtilImoData:
      type: object
      properties:
        input:
          type: string
        normalised:
          type: string
        valid:
          type: boolean
        reason:
          type:
            - "null"
            - string
        standard:
          type: string
        caveat:
          type: string
      required:
        - input
        - normalised
        - valid
        - reason
        - standard
        - caveat
    UtilCheckdigitData:
      type: object
      properties:
        algorithm:
          type: string
        mode:
          type: string
        input:
          type: string
        valid:
          type: boolean
        check_digit:
          type: integer
        full_value:
          type: string
      required:
        - algorithm
        - mode
        - input
    UtilGeoData:
      type: object
      properties:
        from:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
          required:
            - lat
            - lon
        to:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
          required:
            - lat
            - lon
        distance_km:
          type: number
        distance_miles:
          type: number
        distance_nautical_miles:
          type: number
        initial_bearing_degrees:
          type: number
        method:
          type: string
        bearing_degrees:
          type: integer
        destination:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
          required:
            - lat
            - lon
      required:
        - from
        - distance_km
        - method
    UtilGeohashData:
      type: object
      properties:
        lat:
          type: number
        lon:
          type: number
        precision:
          type: integer
        geohash:
          type: string
        bounds:
          type: object
          properties:
            lat_min:
              type: number
            lat_max:
              type: number
            lon_min:
              type: number
            lon_max:
              type: number
          required:
            - lat_min
            - lat_max
            - lon_min
            - lon_max
      required:
        - geohash
        - lat
        - lon
    UtilOuiData:
      type: object
      properties:
        input:
          type: string
        oui:
          type: string
        found:
          type: boolean
        locally_administered:
          type: boolean
        multicast:
          type: boolean
        data_generated_at:
          type: string
        vendor:
          type: string
        vendor_country:
          type: string
        caveat:
          type: string
      required:
        - input
        - oui
        - found
        - locally_administered
        - multicast
        - data_generated_at
    UtilAirportData:
      type: object
      properties:
        input:
          type: string
        lookup:
          type: string
        code:
          type: string
        found:
          type: boolean
        airport:
          type: object
          properties:
            ident:
              type: string
            type:
              type: string
            name:
              type: string
            latitude:
              type: number
            longitude:
              type: number
            elevation_ft:
              type: integer
            iso_country:
              type: string
            iso_region:
              type: string
            municipality:
              type: string
            scheduled_service:
              type: boolean
            icao:
              type: string
            iata:
              type: string
          required:
            - ident
            - type
            - name
            - latitude
            - longitude
            - elevation_ft
            - iso_country
            - iso_region
            - municipality
            - scheduled_service
            - icao
            - iata
        data_generated_at:
          type: string
      required:
        - input
        - lookup
        - code
        - found
        - airport
        - data_generated_at
    UtilTzData:
      type: object
      properties:
        input:
          type: string
        zone:
          type: string
        canonical_zone:
          type: string
        valid:
          type: boolean
        at:
          type: string
        utc_offset:
          type: string
        utc_offset_minutes:
          type: integer
        abbreviation:
          type: string
        observes_dst:
          type: boolean
        is_dst:
          type: boolean
        standard_offset:
          type: string
        countries:
          type: array
          items:
            type: string
        coordinates:
          type: string
        note:
          type: string
        data_generated_at:
          type: string
        country:
          type: string
        found:
          type: boolean
        zones:
          type: array
          items:
            type: string
      required:
        - input
        - data_generated_at
    UtilCurrencyData:
      type: object
      properties:
        input:
          type: string
        code:
          type: string
        found:
          type: boolean
        status:
          type: string
        name:
          type: string
        numeric_code:
          type: string
        minor_units:
          type: integer
        entities:
          type: array
          items:
            type: string
        data_generated_at:
          type: string
      required:
        - input
        - code
        - found
        - status
        - name
        - numeric_code
        - minor_units
        - entities
        - data_generated_at
    UtilLocodeData:
      type: object
      properties:
        input:
          type: string
        locode:
          type: string
        found:
          type: boolean
        entry:
          type: object
          properties:
            locode:
              type: string
            country:
              type: string
            location:
              type: string
            name:
              type: string
            subdivision:
              type: string
            status:
              type: string
            status_meaning:
              type: string
            functions:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  meaning:
                    type: string
                required:
                  - code
                  - meaning
            function_raw:
              type: string
            latitude:
              type: "null"
            longitude:
              type: "null"
            iata:
              type: "null"
          required:
            - locode
            - country
            - location
            - name
            - subdivision
            - status
            - status_meaning
            - functions
            - function_raw
            - latitude
            - longitude
            - iata
        data_generated_at:
          type: string
      required:
        - input
        - locode
        - found
        - entry
        - data_generated_at
