{"openapi":"3.1.0","info":{"title":"vinapi.app API","version":"1.0.0","description":"Decode a 17-character VIN into structured vehicle data. Structural fields (WMI, check digit, model year, region, plant, serial) are computed deterministically from the VIN standard; attribute fields (make, model, engine, …) come from data providers. Every field records its `source`, and missing values are `null` — never guessed."},"servers":[{"url":"https://www.vinapi.app","description":"Production"},{"url":"http://localhost:3000","description":"Local dev"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Decode","description":"VIN decoding endpoints"}],"paths":{"/api/v1/decode":{"post":{"tags":["Decode"],"summary":"Decode a single VIN","operationId":"decodeVin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeRequest"},"examples":{"honda":{"value":{"vin":"1HGCM82633A004352"}}}}}},"responses":{"200":{"description":"Decoded vehicle.","headers":{"X-RateLimit-Limit":{"description":"Per-minute request ceiling for the caller's plan.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window / month.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the burst window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VinDecodeResult"}}}}}},"400":{"description":"Error. Body is `{ error: { code, message } }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Error. Body is `{ error: { code, message } }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Error. Body is `{ error: { code, message } }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Error. Body is `{ error: { code, message } }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/decode/batch":{"post":{"tags":["Decode"],"summary":"Decode up to 50 VINs","description":"Metered per VIN: a batch of N consumes N quota units. Malformed VINs are not rejected wholesale — each comes back with `valid:false` and per-item `errors`.","operationId":"decodeVinBatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeBatchRequest"},"examples":{"two":{"value":{"vins":["1HGCM82633A004352","WVWZZZ1JZ3W386752"]}}}}}},"responses":{"200":{"description":"Decoded vehicles, in request order.","headers":{"X-RateLimit-Limit":{"description":"Per-minute request ceiling for the caller's plan.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window / month.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the burst window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","count"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VinDecodeResult"}},"count":{"type":"integer"}}}}}},"400":{"description":"Error. Body is `{ error: { code, message } }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Error. Body is `{ error: { code, message } }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Error. Body is `{ error: { code, message } }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Error. Body is `{ error: { code, message } }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer vin_live_..."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"DecodeRequest":{"type":"object","required":["vin"],"properties":{"vin":{"type":"string","minLength":17,"maxLength":17,"example":"1HGCM82633A004352"}}},"DecodeBatchRequest":{"type":"object","required":["vins"],"properties":{"vins":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}}},"CheckDigit":{"type":"object","description":"ISO 3780 check digit (position 9). `valid:false` is a quality signal, NOT grounds for rejecting a VIN — many valid EU/Asian VINs legitimately fail it.","properties":{"expected":{"type":["string","null"]},"actual":{"type":["string","null"]},"valid":{"type":"boolean"},"applicable":{"type":"boolean"}}},"Vehicle":{"type":"object","properties":{"make":{"type":["string","null"]},"model":{"type":["string","null"]},"modelYear":{"type":["integer","null"]},"yearAmbiguous":{"type":"boolean"},"yearCandidates":{"type":"array","items":{"type":"integer"}},"series":{"type":["string","null"]},"trim":{"type":["string","null"]},"bodyClass":{"type":["string","null"]},"vehicleType":{"type":["string","null"]},"doors":{"type":["integer","null"]}}},"Engine":{"type":"object","properties":{"cylinders":{"type":["integer","null"]},"displacementL":{"type":["number","null"]},"fuelType":{"type":["string","null"]},"powerKW":{"type":["number","null"]}}},"ProviderError":{"type":"object","properties":{"code":{"type":"string"},"text":{"type":"string"}}},"Sources":{"type":"object","properties":{"structural":{"type":"string","enum":["internal"]},"attributes":{"description":"Which provider supplied attributes, or null if none was available.","type":["string","null"],"enum":["cache","vpic","commercial",null]}}},"VinDecodeResult":{"type":"object","properties":{"vin":{"type":"string"},"squishVin":{"type":["string","null"],"description":"Positions 1-8 + 10 — the cache pattern key (no serial number)."},"valid":{"type":"boolean","description":"Structural validity (length + charset). Not gated on the check digit."},"standard":{"type":"string","enum":["iso-3779","pre-1981","non-standard"]},"checkDigit":{"$ref":"#/components/schemas/CheckDigit"},"wmi":{"type":["string","null"]},"manufacturer":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"vehicleClass":{"type":["string","null"],"enum":["truck","trailer","bus","van","incomplete-chassis","municipal","construction","car",null],"description":"Broad vehicle class derived from the WMI. A routing/display hint — NOT the EU vehicle category (M2/M3, N1-N3, O1-O4), which comes only from the registration record or Certificate of Conformity. Distinct from `vehicle.vehicleType`, which is provider-sourced and uses the provider's own vocabulary; the two can differ for the same vehicle."},"vehicle":{"$ref":"#/components/schemas/Vehicle"},"engine":{"$ref":"#/components/schemas/Engine"},"plant":{"type":["string","null"]},"serialNumber":{"type":["string","null"]},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ProviderError"}},"sources":{"$ref":"#/components/schemas/Sources"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"One of: invalid_body, invalid_vin, invalid_batch, missing_api_key, invalid_api_key, subscription_inactive, rate_limited, quota_exceeded, decode_failed."},"message":{"type":"string"}}}}}}}}