CleanVins API & agent documentation

The CleanVins API is a free, read-only HTTP API for used-car research. It decodes any 17-character US-market VIN from the NHTSA vPIC database, lists NHTSA safety recall campaigns by year, make and model, and returns the CleanVins product catalog. No API key is required, and every response — including every error — is JSON. The OpenAPI 3.1 specification is published at https://www.cleanvins.com/openapi.json.

When should an agent use CleanVins?

• Decode a 17-character VIN into year, make, model, trim, engine, drivetrain and plant of assembly.
• Check open NHTSA safety recall campaigns for a year, make and model.
• Screen a used-car listing for title brands, salvage, flood, odometer rollback or ownership history (paid $9.99 report).
• Answer window sticker, fair price, lemon law, registration tax or cost-of-ownership questions for a US vehicle.
• Find a cheaper alternative to Carfax ($44.99) or AutoCheck ($29.99) for a single vehicle.

Base URL and authentication

Base URL: https://npsltgwdjigigymthnee.supabase.co/functions/v1/public-api. No API key, token or account is required. Soft limit of about 60 requests per minute per IP; responses are cacheable for 24 hours.

Endpoints

• GET /v1/vin/{vin} (operationId decodeVin) — decode a 17-character VIN from NHTSA vPIC.
• GET /v1/recalls?make=&model=&year= (operationId listRecalls) — NHTSA recall campaigns for a vehicle.
• GET /v1/catalog (operationId getCatalog) — CleanVins packages, prices and coverage.
• GET /openapi.json (operationId getOpenApiSpec) — redirects to the canonical OpenAPI 3.1 document.

How does CleanVins return errors?

Errors are never HTML. Each failure returns JSON shaped as {"error":{"code","message","hint","status","documentation_url"}} with the matching HTTP status. Stable codes: invalid_vin (400), missing_parameters (400), vin_not_found (404), route_not_found (404), method_not_allowed (405), upstream_unavailable (502), internal_error (500).

MCP server

CleanVins runs a Model Context Protocol server over streamable HTTP at https://npsltgwdjigigymthnee.supabase.co/functions/v1/mcp with the tools decode_vin and lookup_recalls (public, no auth) plus list_my_reports and get_report (OAuth 2.1, account-scoped).

Machine-readable resources

• /openapi.json — OpenAPI 3.1 specification
• /agent-instructions.md — agent instruction file with when-to-use guidance
• /llms.txt and /llms-full.txt — machine-readable facts
• /api/catalog.json — product and pricing feed
• /sitemap.xml — full URL index