{"openapi":"3.1.0","info":{"title":"freevininfo.com VIN API","version":"1.0.0","description":"Free vehicle specifications and year/make/model recall campaigns from NHTSA. No accident, damage, title, theft, salvage, or ownership records. Best-effort limit: 20 requests per 60 seconds per client per running server instance; this is not a global quota. Preview deployments may require Vercel authorization. See /api-docs for usage and coverage."},"servers":[{"url":"/","description":"The origin serving this specification. Production: https://freevininfo.com. Protected previews require Vercel access."}],"security":[],"paths":{"/api/decode":{"get":{"operationId":"decodeVin","summary":"Decode a VIN and retrieve public model-level recall campaigns","parameters":[{"name":"vin","in":"query","required":true,"description":"Complete 17-character VIN. Leading/trailing whitespace is trimmed and letters are uppercased.","schema":{"type":"string","minLength":17,"maxLength":17,"pattern":"^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$"},"example":"1HGCM82633A004352"}],"responses":{"200":{"description":"Decoded vehicle. Check recallStatus before interpreting recalls. Missing fields are empty strings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"Invalid VIN format, missing VIN, or malformed JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"NHTSA could not confidently identify the VIN, or reported a check-digit failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-instance burst limit exceeded. Wait at least Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Unexpected upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"NHTSA is temporarily unavailable or timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"decodeVinPost","summary":"Decode a VIN using a JSON request body","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vin"],"properties":{"vin":{"type":"string","minLength":17,"maxLength":17,"pattern":"^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$"}}},"example":{"vin":"1HGCM82633A004352"}}}},"responses":{"200":{"description":"Decoded vehicle. Check recallStatus before interpreting recalls. Missing fields are empty strings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"Invalid VIN format, missing VIN, or malformed JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"NHTSA could not confidently identify the VIN, or reported a check-digit failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-instance burst limit exceeded. Wait at least Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Unexpected internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Unexpected upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"NHTSA is temporarily unavailable or timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Vehicle":{"type":"object","description":"Manufacturer-reported values. Empty strings mean the source did not report a value. They do not establish that a feature is absent.","required":["vin","year","make","model","trim","engine","fuel","body","drive","plant","country","transmission","doors"],"properties":{"vin":{"type":"string"},"year":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"trim":{"type":"string"},"engine":{"type":"string"},"fuel":{"type":"string"},"body":{"type":"string"},"drive":{"type":"string"},"plant":{"type":"string"},"country":{"type":"string"},"transmission":{"type":"string"},"doors":{"type":"string"}}},"Recall":{"type":"object","description":"A campaign matching the vehicle's year/make/model, not a confirmed open recall for this VIN. date is normalized to YYYY-MM-DD when NHTSA's date format is recognized; otherwise it retains the source value. id is the campaign number.","required":["id","component","date","summary","consequence","remedy","notes"],"properties":{"id":{"type":"string"},"component":{"type":"string"},"date":{"type":"string"},"summary":{"type":"string"},"consequence":{"type":"string"},"remedy":{"type":"string"},"notes":{"type":"string"}}},"Source":{"type":"object","required":["name","url","retrievedAt","cacheTtlSeconds"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"retrievedAt":{"type":["string","null"],"format":"date-time","description":"Actual source retrieval time. null when recall lookup is unavailable."},"cacheTtlSeconds":{"type":"integer"}}},"Report":{"type":"object","required":["apiVersion","vehicle","specsCheckedAt","specsCached","recalls","recallsCheckedAt","recallStatus","sample","reportUrl","sources","coverage","warnings"],"properties":{"apiVersion":{"type":"string","const":"1.0"},"vehicle":{"$ref":"#/components/schemas/Vehicle"},"specsCheckedAt":{"type":"string","format":"date-time"},"specsCached":{"type":"boolean","description":"Whether this request hit the local cache or shared in-flight work. false does not rule out a shared Vercel Data Cache hit."},"recalls":{"type":"array","items":{"$ref":"#/components/schemas/Recall"}},"recallsCheckedAt":{"type":["string","null"],"format":"date-time"},"recallStatus":{"type":"string","enum":["available","unavailable"]},"sample":{"type":"boolean","const":false},"reportUrl":{"type":"string","format":"uri","description":"Canonical human-readable report URL on https://freevininfo.com."},"sources":{"type":"object","required":["specifications","recalls"],"properties":{"specifications":{"$ref":"#/components/schemas/Source"},"recalls":{"allOf":[{"$ref":"#/components/schemas/Source"},{"type":"object","required":["matchedBy","vinSpecificRepairStatus"],"properties":{"matchedBy":{"type":"array","items":{"type":"string"},"const":["model_year","make","model"]},"vinSpecificRepairStatus":{"type":"string","const":"not_checked"}}}]}}},"coverage":{"type":"object","required":["includes","excludes","limitations"],"properties":{"includes":{"type":"array","items":{"type":"string"}},"excludes":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"string"},"description":"An unavailable recall service returns an explicit warning rather than a negative result."}}},"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["INVALID_REQUEST","VIN_NOT_IDENTIFIED","RATE_LIMITED","UPSTREAM_ERROR","UPSTREAM_UNAVAILABLE","INTERNAL_ERROR"]}}}}}}