{
  "openapi": "3.1.0",
  "info": {
    "title": "Vindex API",
    "version": "0.1.0",
    "summary": "Canada-aware vehicle intelligence for AI agents — per-call, no signup.",
    "description": "Vehicle Intelligence for AI agents. Pay per call with x402 (USDC on Base or Solana) to decode any 17-char VIN ($0.01), read MERGED US (NHTSA) + Canada (Transport Canada) recalls ($0.01), and get reliability stats, LLM-clustered known-issue reports (every issue cites verified ODI complaint numbers), and itemized used-car closing costs for Ontario + all 50 US states & DC. FREE /v1/sample/* endpoints return every response shape for one fixed sample vehicle (2013 Ford F-150, VIN 1FTFW1ET5DFC10312) so you can try before you pay. Every JSON object response carries a legal `disclaimer` field. Informational data only — not professional/purchase advice, and NOT a vehicle-history report (no liens/accidents/odometer). Contains information licensed under the Open Government Licence – Canada.",
    "termsOfService": "https://api.vindexapi.dev/terms.txt",
    "contact": { "name": "Vindex", "url": "https://api.vindexapi.dev", "email": "jcislo918@gmail.com" },
    "license": { "name": "Proprietary — derived intelligence licensed for your own use; resale/redistribution not permitted. Underlying data: NHTSA (US public domain) + Transport Canada (OGL–Canada)." }
  },
  "servers": [{ "url": "https://api.vindexapi.dev", "description": "Vindex public edge" }],
  "externalDocs": { "description": "Agent-facing reference (llms.txt)", "url": "https://api.vindexapi.dev/llms.txt" },
  "tags": [
    { "name": "free", "description": "No auth, no payment. Every JSON object response carries a `disclaimer`." },
    { "name": "paid", "description": "x402 V2 per-call pricing (USDC on Base eip155:8453 or Solana). Compute-first / settle-after." }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["free"],
        "operationId": "getHealth",
        "summary": "Liveness + configured payment mode",
        "responses": {
          "200": {
            "description": "Service is up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "service": { "type": "string", "const": "vindex-api" },
                    "mode": { "type": "string", "enum": ["live", "mock"], "description": "x402 payment plane mode" },
                    "ts": { "type": "string", "format": "date-time" },
                    "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/decode": {
      "get": {
        "tags": ["paid"],
        "operationId": "decodeVin",
        "summary": "NHTSA vPIC normalized VIN decode ($0.01)",
        "description": "Paid ($0.01 USDC via x402). Decodes a 17-character VIN via NHTSA vPIC. 90-day read-through cache; stale served on upstream failure. Without a payment credential returns a 402 challenge; compute-first / settle-after (never charged for errors). Free fixed-sample preview of this exact shape: GET /v1/sample/decode.",
        "parameters": [
          { "name": "vin", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" }, "description": "17-char VIN (A–Z0–9, excluding I/O/Q)." }
        ],
        "security": [{ "x402": [] }],
        "responses": {
          "200": {
            "description": "Decoded vehicle.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vin": { "type": "string" },
                    "vehicle": { "$ref": "#/components/schemas/DecodedVehicle" },
                    "provenance": {
                      "type": "object",
                      "properties": {
                        "source": { "type": "string", "const": "nhtsa-vpic" },
                        "fetchedAt": { "type": "string", "format": "date-time" },
                        "cache": { "type": "string", "enum": ["hit", "miss"] }
                      }
                    },
                    "charged": { "type": "boolean", "const": true },
                    "payment": { "$ref": "#/components/schemas/PaymentReceipt" },
                    "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidVin" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "422": { "$ref": "#/components/responses/DecodeFailed" },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/v1/recalls": {
      "get": {
        "tags": ["paid"],
        "operationId": "getMergedRecalls",
        "summary": "Merged US (NHTSA) + Canada (Transport Canada) recalls ($0.01)",
        "description": "Paid ($0.01 USDC via x402). Decodes the VIN, then merges NHTSA (US) and Transport Canada (CA) recalls into one response — the only API combining both. 24h cache per source; stale served on failure. Canadian detail capped at the 25 most-recent recalls. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/recalls.",
        "parameters": [
          { "name": "vin", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" } }
        ],
        "security": [{ "x402": [] }],
        "responses": {
          "200": {
            "description": "Merged recalls.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vin": { "type": "string" },
                    "vehicle": { "$ref": "#/components/schemas/VehicleRef" },
                    "recalls": {
                      "type": "object",
                      "properties": {
                        "us": { "type": "array", "items": { "$ref": "#/components/schemas/UsRecall" } },
                        "canada": { "type": "array", "items": { "$ref": "#/components/schemas/CaRecall" } }
                      }
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "us": { "type": "integer" },
                        "canada": { "type": "integer" }
                      }
                    },
                    "provenance": {
                      "type": "object",
                      "properties": {
                        "nhtsaFetchedAt": { "type": "string", "format": "date-time" },
                        "tcFetchedAt": { "type": "string", "format": "date-time" },
                        "attribution": { "type": "string", "const": "Contains information licensed under the Open Government Licence – Canada." }
                      }
                    },
                    "charged": { "type": "boolean", "const": true },
                    "payment": { "$ref": "#/components/schemas/PaymentReceipt" },
                    "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidVin" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "422": { "$ref": "#/components/responses/DecodeFailed" },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/v1/sample/decode": {
      "get": {
        "tags": ["free"],
        "operationId": "sampleDecode",
        "summary": "FREE sample VIN decode (fixed sample vehicle)",
        "description": "Free, no payment. Always returns the NHTSA vPIC decode for the fixed sample vehicle (2013 Ford F-150, VIN 1FTFW1ET5DFC10312), computed live. Same shape as paid GET /v1/decode plus top-level `sample: true` and `note`.",
        "responses": {
          "200": { "description": "Sample decode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleEnvelope" } } } },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/v1/sample/recalls": {
      "get": {
        "tags": ["free"],
        "operationId": "sampleRecalls",
        "summary": "FREE sample merged US + Canada recalls (fixed sample vehicle)",
        "description": "Free, no payment. Merged NHTSA (US) + Transport Canada (CA) recalls for the fixed sample vehicle. Same shape as paid GET /v1/recalls plus `sample: true` and `note`.",
        "responses": {
          "200": { "description": "Sample recalls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleEnvelope" } } } },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/v1/sample/reliability": {
      "get": {
        "tags": ["free"],
        "operationId": "sampleReliability",
        "summary": "FREE sample reliability stats (fixed sample vehicle)",
        "description": "Free, no payment. Reliability stats for the fixed sample vehicle. Same shape as paid GET /v1/reliability plus `sample: true` and `note`.",
        "responses": {
          "200": { "description": "Sample reliability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleEnvelope" } } } },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/v1/sample/known-issues": {
      "get": {
        "tags": ["free"],
        "operationId": "sampleKnownIssues",
        "summary": "FREE sample known-issues (fixed sample vehicle)",
        "description": "Free, no payment. LLM-clustered known-issues for the fixed sample vehicle. Same shape as paid GET /v1/known-issues plus `sample: true` and `note`. A non-'ok' synthesis status is served as-is with 200 (samples never 503).",
        "responses": {
          "200": { "description": "Sample known-issues (any synthesis status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleEnvelope" } } } },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/v1/sample/purchase-costs": {
      "get": {
        "tags": ["free"],
        "operationId": "samplePurchaseCosts",
        "summary": "FREE sample closing costs for both countries (fixed sample inputs)",
        "description": "Free, no payment. Returns `{ sample: true, note, ca, us }`: `ca` is the Ontario $25,000-private result (same shape as paid GET /v1/ca/purchase-costs) and `us` is the California $25,000-private result (same shape as paid GET /v1/us/purchase-costs).",
        "responses": {
          "200": { "description": "Sample Ontario purchase costs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleEnvelope" } } } }
        }
      }
    },
    "/v1/reliability": {
      "get": {
        "tags": ["paid"],
        "operationId": "getReliability",
        "summary": "Reliability snapshot for a VIN ($0.05)",
        "description": "Paid ($0.05 USDC via x402). Complaint stats (top NHTSA components; severity signals crashes/fires/injuries summed from the underlying complaint records) plus US and Canada recall counts including Canadian units affected. v0 returns raw counts, not fleet/segment percentiles (roadmap). Without a payment credential returns a 402 challenge; compute-first / settle-after (never charged for errors).",
        "parameters": [
          { "name": "vin", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" } }
        ],
        "security": [{ "x402": [] }],
        "responses": {
          "200": {
            "description": "Reliability snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vin": { "type": "string" },
                    "vehicle": { "$ref": "#/components/schemas/VehicleRef" },
                    "complaints": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer", "description": "Total upstream complaint count." },
                        "topComponents": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "component": { "type": "string" },
                              "count": { "type": "integer" }
                            }
                          }
                        },
                        "severity": {
                          "type": "object",
                          "description": "Summed from the underlying NHTSA complaint records.",
                          "properties": {
                            "crashes": { "type": "integer" },
                            "fires": { "type": "integer" },
                            "injuries": { "type": "integer" }
                          }
                        }
                      }
                    },
                    "recalls": {
                      "type": "object",
                      "properties": {
                        "usCount": { "type": "integer" },
                        "canadaCount": { "type": "integer" },
                        "canadaUnitsAffected": { "type": ["integer", "null"], "description": "Sum of unitsAffected across the vehicle's Canadian recalls." }
                      }
                    },
                    "provenance": {
                      "type": "object",
                      "properties": {
                        "complaintsFetchedAt": { "type": "string", "format": "date-time" },
                        "nhtsaFetchedAt": { "type": "string", "format": "date-time" },
                        "tcFetchedAt": { "type": "string", "format": "date-time" },
                        "attribution": { "type": "string" }
                      }
                    },
                    "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidVin" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "422": { "$ref": "#/components/responses/DecodeFailed" },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/v1/known-issues": {
      "get": {
        "tags": ["paid"],
        "operationId": "getKnownIssues",
        "summary": "LLM-clustered named failure modes with verified ODI citations ($0.25)",
        "description": "Paid ($0.25 USDC via x402). Clusters NHTSA owner complaints into named failure modes; EVERY cited ODI number is programmatically validated against the input complaint set (hallucination-gated) and every issue carries ≥2 verified citations. Severity signals per issue are summed from the CITED complaints only. Refuses UNCHARGED below 15 complaints (returns 200 status:insufficient_data). 90-day cache.",
        "parameters": [
          { "name": "vin", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" } }
        ],
        "security": [{ "x402": [] }],
        "responses": {
          "200": {
            "description": "Known-issues result (ok, insufficient_data, or synthesis_unavailable). The latter two are returned UNCHARGED.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/KnownIssuesOk" },
                    { "$ref": "#/components/schemas/KnownIssuesInsufficient" },
                    { "$ref": "#/components/schemas/KnownIssuesUnavailable" }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidVin" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "422": { "$ref": "#/components/responses/DecodeFailed" },
          "502": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/v1/ca/purchase-costs": {
      "get": {
        "tags": ["paid"],
        "operationId": "getCaPurchaseCosts",
        "summary": "Itemized Canada per-jurisdiction used-vehicle closing costs ($0.02)",
        "description": "Paid ($0.02 USDC via x402). Government-imposed closing costs of buying a used passenger vehicle in any of Canada's 10 provinces + 3 territories (BC, AB, SK, MB, ON, QC, NB, NS, PE, NL, YT, NT, NU): provincial/territorial sales tax (PST/RST/QST/HST or GST-only) plus transfer/registration/plate fees and inspection, each line with a source URL and confidence. Figures verified 2026-07-04 against provincial/territorial sources. Tax is flat on the whole price at the highest bracket whose threshold the price meets (BC private sales tier at 12% → 15% ≥ $125,000 → 20% ≥ $150,000); Alberta and the three territories levy no tax on private sales; dealer sales add 5% federal GST except in HST provinces (ON/NB/NS/PE/NL) where a single HST rate applies. Where a base-rule book-value floor exists (Red Book / Black Book / estimated value), a caveat notes the figure assumes price ≥ book value. Compute-first / settle-after.",
        "parameters": [
          { "name": "province", "in": "query", "required": true, "schema": { "type": "string", "enum": ["BC", "AB", "SK", "MB", "ON", "QC", "NB", "NS", "PE", "NL", "YT", "NT", "NU"] }, "description": "Two-letter province/territory code (case-insensitive): all 10 provinces + 3 territories." },
          { "name": "price", "in": "query", "required": true, "schema": { "type": "number", "minimum": 0.01 }, "description": "Agreed sale price in CAD (> 0, ≤ 5,000,000)." },
          { "name": "sale_type", "in": "query", "required": true, "schema": { "type": "string", "enum": ["private", "dealer"] }, "description": "Private sale (provincial tax + private-sale fees) or dealer sale (GST + provincial or HST)." },
          { "name": "buyer_has_plates", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Selects plate-dependent fee lines where the jurisdiction distinguishes them — e.g. Ontario: true → vehicle permit only ($32); false → permit + new plate ($59)." },
          { "name": "family_gift", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Private sales only — applies the jurisdiction's family/related-individual gift exemption ($0 tax) where one exists." }
        ],
        "security": [{ "x402": [] }],
        "responses": {
          "200": {
            "description": "Itemized Canadian per-jurisdiction purchase costs.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OntarioPurchaseCosts" } } }
          },
          "400": { "description": "Validation failed (bad price, unknown province/territory, invalid sale_type).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "disclaimer": { "$ref": "#/components/schemas/Disclaimer" } } } } } },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/us/purchase-costs": {
      "get": {
        "tags": ["paid"],
        "operationId": "getUsPurchaseCosts",
        "summary": "Itemized US per-state used-vehicle closing costs ($0.02)",
        "description": "Paid ($0.02 USDC via x402). Government-imposed closing costs of buying a used passenger vehicle in any of the 50 US states or DC (sales/use/excise tax, title, first-year registration, inspection, and — for dealer sales — a dealer documentation fee), each line with a source URL and confidence. Figures verified against state sources as of 2026-07-04. Handles special regimes automatically: DC returns a tiered title-excise range (no percentage sales tax); IL private-party sales use a flat RUT-50 fee table (null-amount market estimate) while the 6.25%+local rate applies to IL dealer sales only; SC's 5% IMF is capped at $500; and AK/AZ/HI/MT/NV/NH/OR levy no state sales tax on private-party sales. Compute-first / settle-after.",
        "parameters": [
          { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "description": "Two-letter state code (case-insensitive), one of the 50 states or DC." },
          { "name": "price", "in": "query", "required": true, "schema": { "type": "number", "minimum": 0.01, "maximum": 5000000 }, "description": "Agreed sale price in USD (> 0, ≤ 5,000,000)." },
          { "name": "sale_type", "in": "query", "required": true, "schema": { "type": "string", "enum": ["private", "dealer"] }, "description": "Private-party or dealer sale. Dealer sales add a dealer_doc_fee line and are where a full trade-in credit is applied." },
          { "name": "trade_in", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Trade-in value in USD (≥ 0, < price). Deducted from the tax base only for a dealer sale in a state granting a FULL trade-in credit." },
          { "name": "local_rate", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 15 }, "description": "Exact county/city surtax percentage (0–15). When omitted, the sales-tax line carries a range up to the state's maximum local rate." }
        ],
        "security": [{ "x402": [] }],
        "responses": {
          "200": {
            "description": "Itemized US per-state purchase costs.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsPurchaseCosts" } } }
          },
          "400": { "description": "Validation failed (unknown state, bad price/trade_in/local_rate, invalid sale_type).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "disclaimer": { "$ref": "#/components/schemas/Disclaimer" } } } } } },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "InvalidVin": {
        "description": "VIN failed shape validation (must be 17 chars, no I/O/Q).",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "disclaimer": { "$ref": "#/components/schemas/Disclaimer" } } } } }
      },
      "DecodeFailed": {
        "description": "vPIC could not resolve make/model/year for this VIN.",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "vpicErrorText": { "type": "string" }, "disclaimer": { "$ref": "#/components/schemas/Disclaimer" } } } } }
      },
      "UpstreamUnavailable": {
        "description": "An upstream public-data source was unavailable and no cached data existed.",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "upstream unavailable" }, "disclaimer": { "$ref": "#/components/schemas/Disclaimer" } } } } }
      },
      "PaymentRequired": {
        "description": "x402 V2 payment challenge. Sign an `exact` USDC authorization for one accepts[] rail (Base or Solana), then retry with the PAYMENT-SIGNATURE (V2) or X-PAYMENT (legacy) header. You are not charged for errors or below-threshold answers.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } }
      }
    },
    "securitySchemes": {
      "x402": {
        "type": "http",
        "scheme": "x402",
        "description": "Custom HTTP 402 payment flow (x402 V2). The server answers an unpaid paid-route request with a 402 whose body is a PaymentRequired envelope (x402Version + accepts[] + terms). Each accepts[] entry is an `exact`-scheme USDC rail: Base (eip155:8453, EIP-3009) or Solana (SPL TransferChecked). Sign ONE rail and retry the same request with the `PAYMENT-SIGNATURE` header (x402 V2 clients) or the legacy `X-PAYMENT` header. Per-call pricing; compute-first / settle-after."
      }
    },
    "schemas": {
      "Disclaimer": {
        "type": "string",
        "description": "Legal disclaimer stamped onto every JSON object response.",
        "example": "Vindex provides informational vehicle data aggregated from public sources (NHTSA, Transport Canada). It is not professional, legal, or purchasing advice, and is provided as-is without warranty. Contains information licensed under the Open Government Licence – Canada."
      },
      "PaymentReceipt": {
        "type": "object",
        "description": "Settlement facts echoed on a charged (200) paid response.",
        "properties": {
          "txHash": { "type": ["string", "null"] },
          "network": { "type": ["string", "null"] },
          "priceUsd": { "type": "number", "example": 0.01 },
          "payer": { "type": "string", "description": "Payer recovered from the payment — never a client-claimed field." }
        }
      },
      "SampleEnvelope": {
        "type": "object",
        "description": "A free /v1/sample/* response: the same body as the paid per-VIN twin, always for the fixed sample vehicle (2013 Ford F-150, VIN 1FTFW1ET5DFC10312) or fixed sample input, with a top-level `sample` flag and `note`. Never carries payment fields.",
        "properties": {
          "sample": { "type": "boolean", "const": true },
          "note": { "type": "string", "example": "Fixed sample vehicle (2013 Ford F-150, VIN 1FTFW1ET5DFC10312). Pay per-call for any VIN — see /discovery." },
          "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
        }
      },
      "DecodedVehicle": {
        "type": "object",
        "description": "Normalized NHTSA vPIC decode. Empty vPIC strings are returned as null.",
        "properties": {
          "vin": { "type": "string", "example": "1FA6P8TH5J5100000" },
          "year": { "type": "integer", "example": 2018 },
          "make": { "type": "string", "example": "FORD" },
          "model": { "type": "string", "example": "Mustang" },
          "trim": { "type": ["string", "null"] },
          "series": { "type": ["string", "null"] },
          "bodyClass": { "type": ["string", "null"], "example": "Coupe" },
          "vehicleType": { "type": ["string", "null"], "example": "PASSENGER CAR" },
          "driveType": { "type": ["string", "null"], "example": "RWD" },
          "engine": {
            "type": "object",
            "properties": {
              "model": { "type": ["string", "null"] },
              "cylinders": { "type": ["integer", "null"], "example": 4 },
              "displacementL": { "type": ["number", "null"], "example": 2.3 },
              "fuelType": { "type": ["string", "null"], "example": "Gasoline" }
            }
          },
          "plantCountry": { "type": ["string", "null"], "example": "UNITED STATES (USA)" },
          "vpicErrorCode": { "type": "string", "description": "Raw vPIC ErrorCode.", "example": "0" },
          "vpicErrorText": { "type": ["string", "null"], "description": "Populated only when vpicErrorCode is not '0'." }
        }
      },
      "VehicleRef": {
        "type": "object",
        "description": "Minimal vehicle identity echoed on recall/paid responses.",
        "properties": {
          "year": { "type": "integer", "example": 2018 },
          "make": { "type": "string", "example": "FORD" },
          "model": { "type": "string", "example": "Mustang" }
        }
      },
      "UsRecall": {
        "type": "object",
        "properties": {
          "campaign": { "type": "string", "example": "18V123000" },
          "component": { "type": "string", "example": "ELECTRICAL SYSTEM" },
          "summary": { "type": "string" },
          "consequence": { "type": "string" },
          "remedy": { "type": "string" },
          "reportedDate": { "type": "string", "example": "2018-03-01" }
        }
      },
      "CaRecall": {
        "type": "object",
        "description": "Transport Canada recall (OGL–Canada).",
        "properties": {
          "recallNumber": { "type": "string", "example": "2018-123" },
          "systemType": { "type": ["string", "null"], "example": "Electrical" },
          "summary": { "type": ["string", "null"] },
          "unitsAffected": { "type": ["integer", "null"], "example": 4200 },
          "recallDate": { "type": ["string", "null"], "example": "2018-03-15" }
        }
      },
      "KnownIssue": {
        "type": "object",
        "properties": {
          "title": { "type": "string", "example": "Electric power steering assist failure" },
          "componentTags": { "type": "array", "items": { "type": "string" }, "example": ["STEERING", "ELECTRICAL SYSTEM"] },
          "odiNumbers": { "type": "array", "items": { "type": "integer" }, "description": "≥2 verified NHTSA ODI complaint numbers, each present in the input complaint set.", "example": [11234567, 11245678] },
          "count": { "type": "integer", "description": "odiNumbers.length." },
          "severitySignals": {
            "type": "object",
            "description": "Summed from the CITED complaints only.",
            "properties": {
              "crashes": { "type": "integer" },
              "fires": { "type": "integer" },
              "injuries": { "type": "integer" }
            }
          },
          "trend": { "type": "string", "enum": ["rising", "stable", "declining", "unknown"] },
          "confidence": { "type": "number", "description": "0..1.", "example": 0.82 }
        }
      },
      "KnownIssuesOk": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "const": "ok" },
          "issues": { "type": "array", "items": { "$ref": "#/components/schemas/KnownIssue" } },
          "complaintCount": { "type": "integer" },
          "modelVersion": { "type": "string", "example": "free-chain-medium/v1" },
          "synthesizedAt": { "type": "string", "format": "date-time" },
          "cache": { "type": "string", "enum": ["hit", "miss"] },
          "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
        }
      },
      "KnownIssuesInsufficient": {
        "type": "object",
        "description": "Returned UNCHARGED when the vehicle has fewer than 15 complaints.",
        "properties": {
          "status": { "type": "string", "const": "insufficient_data" },
          "complaintCount": { "type": "integer" },
          "minimum": { "type": "integer", "const": 15 },
          "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
        }
      },
      "KnownIssuesUnavailable": {
        "type": "object",
        "description": "Returned UNCHARGED when synthesis fails.",
        "properties": {
          "status": { "type": "string", "const": "synthesis_unavailable" },
          "reason": { "type": "string", "enum": ["llm_unavailable", "unparseable", "no_grounded_issues"] },
          "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
        }
      },
      "CostLine": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "rst" },
          "label": { "type": "string" },
          "amountCad": { "type": ["number", "null"], "description": "null when only a market range applies." },
          "rangeCad": {
            "type": ["object", "null"],
            "properties": {
              "low": { "type": "number" },
              "high": { "type": "number" },
              "typical": { "type": "string" }
            }
          },
          "kind": { "type": "string", "enum": ["tax", "fee", "market_estimate", "informational"] },
          "paidTo": { "type": "string" },
          "notes": { "type": "string" },
          "sourceUrl": { "type": "string", "format": "uri" },
          "confidence": { "type": "string", "enum": ["high", "medium"] }
        }
      },
      "OntarioPurchaseCosts": {
        "type": "object",
        "description": "Canadian per-jurisdiction purchase-costs result (all 10 provinces + 3 territories).",
        "properties": {
          "country": { "type": "string", "const": "CA" },
          "province": { "type": "string", "description": "Normalized upper-case province/territory code.", "example": "BC" },
          "provinceName": { "type": "string", "example": "British Columbia" },
          "input": {
            "type": "object",
            "properties": {
              "province": { "type": "string" },
              "priceCad": { "type": "number" },
              "saleType": { "type": "string", "enum": ["private", "dealer"] },
              "familyGift": { "type": "boolean" },
              "buyerHasPlates": { "type": "boolean" }
            }
          },
          "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CostLine" } },
          "totalKnownCad": { "type": "number", "description": "Sum of non-null tax + fee amounts." },
          "estimatedTotalRangeCad": {
            "type": "object",
            "description": "Known total widened by each market-estimate / range line; low ≤ high always.",
            "properties": {
              "low": { "type": "number" },
              "high": { "type": "number" }
            }
          },
          "caveats": { "type": "array", "items": { "type": "string" } },
          "rulesAsOf": { "type": "string", "example": "2026-07-04" },
          "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
        }
      },
      "UsCostLine": {
        "type": "object",
        "description": "One US closing-cost line. `amountUsd` is a fixed known cost; `rangeUsd` is present when only a market/tax range is known (amountUsd may then be null).",
        "properties": {
          "id": { "type": "string", "enum": ["sales_tax", "title", "registration", "inspection", "dealer_doc_fee"], "example": "sales_tax" },
          "label": { "type": "string" },
          "amountUsd": { "type": ["number", "null"], "description": "null when only a market/range estimate applies." },
          "rangeUsd": {
            "type": ["object", "null"],
            "properties": {
              "low": { "type": "number" },
              "high": { "type": "number" }
            }
          },
          "kind": { "type": "string", "enum": ["tax", "fee", "market_estimate", "informational"] },
          "paidTo": { "type": "string" },
          "notes": { "type": "string" },
          "sourceUrl": { "type": "string", "format": "uri" },
          "confidence": { "type": "string", "enum": ["high", "medium"] }
        }
      },
      "UsPurchaseCosts": {
        "type": "object",
        "properties": {
          "country": { "type": "string", "const": "US" },
          "state": { "type": "string", "description": "Normalized upper-case state code.", "example": "CA" },
          "stateName": { "type": "string", "example": "California" },
          "input": {
            "type": "object",
            "properties": {
              "state": { "type": "string" },
              "priceUsd": { "type": "number" },
              "saleType": { "type": "string", "enum": ["private", "dealer"] },
              "tradeInUsd": { "type": "number", "description": "0 when not supplied." },
              "localRatePct": { "type": ["number", "null"], "description": "null when not supplied." }
            }
          },
          "lines": { "type": "array", "items": { "$ref": "#/components/schemas/UsCostLine" } },
          "totalKnownUsd": { "type": "number", "description": "Sum of non-null tax + fee amounts (fixed known government costs)." },
          "estimatedTotalRangeUsd": {
            "type": "object",
            "description": "Known total widened by each market-estimate / range line; low ≤ high always.",
            "properties": {
              "low": { "type": "number" },
              "high": { "type": "number" }
            }
          },
          "caveats": { "type": "array", "items": { "type": "string" } },
          "rulesAsOf": { "type": "string", "example": "2026-07-04" },
          "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
        }
      },
      "PaymentRequired": {
        "type": "object",
        "description": "x402 V2 PaymentRequired envelope. accepts[] lists one exact USDC rail per network.",
        "properties": {
          "x402Version": { "type": "integer", "const": 2 },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string", "const": "exact" },
                "network": { "type": "string", "enum": ["eip155:8453", "solana"] },
                "asset": { "type": "string", "const": "USDC" },
                "price": { "type": "string", "description": "USD price string.", "example": "$0.25" },
                "payTo": { "type": "string", "description": "Settlement address for this rail." },
                "description": { "type": "string" },
                "mimeType": { "type": "string", "const": "application/json" }
              }
            }
          },
          "terms": { "type": "string", "format": "uri" },
          "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }
        }
      }
    }
  }
}