{
  "openapi": "3.1.0",
  "info": {
    "title": "AutoPulse API",
    "description": "Automotive intelligence API — 10 endpoints powered by NHTSA, EPA, and live market data. Safety recalls, reliability analysis, DIY repair guides, vehicle comparison, market value, EV break-even, dealer negotiation, pre-purchase inspection, parts pricing, and total cost of ownership. Global recall data (NHTSA, DVSA UK, Transport Canada, ACCC AU, RAPEX EU). All endpoints require x402 payment (USDC on Base mainnet) via the PAYMENT-SIGNATURE header.",
    "version": "1.2.0",
    "contact": {
      "url": "https://autopulse-navy.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://autopulse-navy.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Omit to receive a 402 with payment requirements."
      }
    }
  },
  "paths": {
    "/api/auto/recall": {
      "get": {
        "summary": "NHTSA safety recall lookup",
        "description": "Active safety recalls from NHTSA for any vehicle by VIN or year/make/model. Returns risk level, what fails, consequences, remedy, and action for the owner.",
        "operationId": "autoRecall",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "vin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "17-character VIN"
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "make",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "model",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recall report with risk ratings and remedies"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.05,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Always run first in any used car purchase workflow; feed VIN into /api/auto/problems and /api/auto/value; if recalls found, prioritize remedy status before purchase"
      }
    },
    "/api/auto/problems": {
      "get": {
        "summary": "Known problems and reliability analysis",
        "description": "NHTSA complaint data + owner forum synthesis. Returns reliability verdict, known problems by severity and frequency, typical mileage, repair costs, and DIY feasibility.",
        "operationId": "autoProblems",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "make",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "model",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reliability analysis with known problems ranked by severity"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run after /api/auto/recall to add reliability context; if severe problems found, cross-sell extended warranty; pair with /api/auto/value for sell vs. repair decision"
      }
    },
    "/api/auto/repair": {
      "get": {
        "summary": "DIY repair guide",
        "description": "Step-by-step repair instructions with parts list (Amazon links), tools needed, difficulty rating, time estimate, and DIY vs. shop cost comparison.",
        "operationId": "autoRepair",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "vehicle",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Vehicle descriptor (e.g. 2020-toyota-camry)"
          },
          {
            "name": "job",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repair job (e.g. brake-pads, oil-change, cabin-air-filter)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Step-by-step repair guide with parts and cost estimate"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Follow with Amazon parts affiliate links included in response; pairs with /api/auto/problems to identify which repairs are DIY-feasible vs. shop-required"
      }
    },
    "/api/auto/compare": {
      "get": {
        "summary": "Vehicle comparison",
        "description": "Side-by-side comparison of 2-4 vehicles \u2014 reliability, EPA MPG, 5-year ownership cost, strengths/weaknesses, and overall winner with reasoning.",
        "operationId": "autoCompare",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "vehicles",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated vehicles (e.g. Toyota RAV4,Honda CR-V,Mazda CX-5)"
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Vehicle comparison with winner recommendation"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Use before /api/auto/negotiate to establish target price; follow with /api/auto/recall and /api/auto/problems for complete due diligence"
      }
    },
    "/api/auto/value": {
      "get": {
        "summary": "Market value estimate",
        "description": "Current private party, trade-in, and dealer retail value ranges with sell vs. hold recommendation, depreciation context, and tips to maximize sale price.",
        "operationId": "autoValue",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "vin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "make",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "model",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mileage",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "condition",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "excellent",
                "good",
                "fair",
                "poor"
              ],
              "default": "good"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Market value ranges with sell/hold recommendation"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Central sell/hold decision endpoint — pair with /api/auto/problems (repair cost estimate) and /api/auto/repair (DIY feasibility) before recommending major repair vs. sell"
      }
    },
    "/api/auto/ev-breakeven": {
      "get": {
        "summary": "EV break-even analysis vs. gas vehicle",
        "description": "IRA tax credit eligibility ($7,500 federal + state incentives), fuel cost savings vs comparable gas vehicle, total cost of ownership comparison, and break-even timeline. Covers all EVs eligible for 2025 Clean Vehicle Credit. Global EV incentive context for UK/EU/AU/CA included.",
        "operationId": "autoEVBreakeven",
        "security": [{ "x402": [] }],
        "parameters": [
          { "name": "ev_model", "in": "query", "required": true, "schema": { "type": "string" }, "description": "EV model name (e.g. Tesla Model 3, Chevrolet Bolt, Ford F-150 Lightning)" },
          { "name": "gas_vehicle", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Gas vehicle for comparison (e.g. Toyota Camry, Honda CR-V)" },
          { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "US state for state-level incentives and electricity rates" },
          { "name": "annual_miles", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Annual mileage (default: 12,000)" },
          { "name": "electricity_rate", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Local electricity rate in $/kWh" },
          { "name": "gas_price", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Local gas price in $/gallon" },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "EV break-even analysis with IRA credit and fuel savings calculation" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pairs with GridPulse /api/energy/ev-cost for state-specific electricity rate context; follow with /api/auto/compare to compare EV against alternatives"
      }
    },
    "/api/auto/negotiate": {
      "get": {
        "summary": "Car buying negotiation guide",
        "description": "Dealer negotiation playbook for any new or used vehicle — invoice price vs MSRP, current market conditions (above/below sticker), junk fees to refuse (dealer add-ons, documentation fees, paint sealant), exact scripts for counter-offers, and email template approach for remote negotiation.",
        "operationId": "autoNegotiate",
        "security": [{ "x402": [] }],
        "parameters": [
          { "name": "make", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" } },
          { "name": "trim", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Negotiation playbook with target price, scripts, and junk fee guide" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Use after /api/auto/compare to establish target; run /api/auto/recall and /api/auto/problems before showing up to the dealer — knowledge is leverage"
      }
    },
    "/api/auto/inspect": {
      "get": {
        "summary": "Pre-purchase inspection checklist",
        "description": "Targeted pre-purchase inspection checklist for any vehicle — specific items to check based on known model issues (from NHTSA complaints), what to look for during test drive, red flags that indicate hidden damage or deferred maintenance, and what a professional inspector should verify. Includes European inspection standards (MOT, TÜV) for international buyers.",
        "operationId": "autoInspect",
        "security": [{ "x402": [] }],
        "parameters": [
          { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" } },
          { "name": "make", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "model", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "mileage", "in": "query", "required": false, "schema": { "type": "integer" } },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Customized pre-purchase inspection checklist" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Use alongside /api/auto/recall and /api/auto/problems to build a complete pre-purchase due diligence package; links to professional inspection services included in response"
      }
    },
    "/api/auto/parts": {
      "get": {
        "summary": "Parts pricing and sourcing",
        "description": "Parts pricing comparison across dealers, aftermarket, and salvage sources for any repair job — OEM vs aftermarket quality tradeoffs, average dealer markup, RockAuto and Amazon part numbers where available, and which parts to never buy aftermarket (safety-critical) vs. where aftermarket is equal or better.",
        "operationId": "autoParts",
        "security": [{ "x402": [] }],
        "parameters": [
          { "name": "vehicle", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Vehicle descriptor (e.g. 2019-honda-accord)" },
          { "name": "part", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Part name (e.g. brake-pads, alternator, water-pump)" },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Parts pricing comparison with OEM vs. aftermarket guidance" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Use after /api/auto/repair to price the parts list; pairs with Amazon and RockAuto affiliate links in response"
      }
    },
    "/api/auto/tco": {
      "get": {
        "summary": "Total cost of ownership (5-year)",
        "description": "5-year total cost of ownership analysis — depreciation curve, insurance cost estimate, fuel/electricity cost, scheduled maintenance cost, expected repairs based on reliability data, registration fees, and financing cost. Compares TCO across similar vehicles to identify hidden cost differences.",
        "operationId": "autoTCO",
        "security": [{ "x402": [] }],
        "parameters": [
          { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" } },
          { "name": "make", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "model", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "purchase_price", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Purchase price in USD" },
          { "name": "annual_miles", "in": "query", "required": false, "schema": { "type": "integer" } },
          { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "5-year TCO breakdown with year-by-year cost projection" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Use as the final step in a vehicle purchase decision; pairs with /api/auto/compare for multi-vehicle TCO comparison; EV TCO should pair with GridPulse /api/energy/ev-cost"
      }
    }
  }
}