{"openapi":"3.0.3","info":{"title":"Vehicode API","version":"0.1.0","description":"VIN decoding API for subscriber integrations. Public usage is available for evaluation; subscriber usage uses API keys and monthly plan limits."},"servers":[{"url":"https://vehicode.eu","description":"Production"},{"url":"http://127.0.0.1:3100","description":"Local development"}],"security":[{"ApiKeyAuth":[]},{"BearerApiKey":[]}],"tags":[{"name":"Decode","description":"VIN decoding"},{"name":"Feedback","description":"Decode correction reporting"}],"paths":{"/api/decode":{"post":{"tags":["Decode"],"summary":"Decode a VIN","description":"Returns a normalized vehicle report. Send an API key with `x-api-key` or `Authorization: Bearer` for subscriber usage and monthly plan limits.","operationId":"decodeVin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeRequest"},"examples":{"volkswagen":{"value":{"vin":"WVWZZZAUZHP507470"}}}}}},"responses":{"200":{"description":"Decoded vehicle report","headers":{"X-Vehicode-Auth":{"description":"Authentication mode used for the request.","schema":{"type":"string","enum":["public","subscriber"]}},"X-Vehicode-Client":{"description":"Subscriber workspace slug when an API key is used.","schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeResponse"},"examples":{"success":{"value":{"report":{"vin":"WVWZZZAUZHP507470","wmi":"WVW","vds":"ZZZAUZ","vis":"HP507470","validFormat":true,"manufacturer":"Volkswagen","model":"Golf","bodyStyle":"Combi","modelYear":"2017","vehicleType":"Passenger car","region":"Europe","specs":{"fuelType":"Gasoline","transmission":"Automatic"},"technicalSpecs":{"lengthMm":4284,"widthMm":1789,"heightMm":1491,"wheelbaseMm":2636,"curbWeightKg":1376}},"usage":{"limit":5000,"remaining":4999,"resetAt":"2026-08-01T00:00:00.000Z"}}}}}}},"400":{"description":"Invalid VIN payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"value":{"error":"Please provide a VIN to decode."}}}}}},"401":{"description":"Invalid or inactive API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid or inactive API key."}}}}}},"429":{"description":"Plan or public usage limit reached","headers":{"X-Vehicode-Auth":{"description":"Authentication mode used for the request.","schema":{"type":"string","enum":["public","subscriber"]}},"X-Vehicode-Client":{"description":"Subscriber workspace slug when an API key is used.","schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"},"examples":{"subscriberLimit":{"value":{"error":"Monthly subscriber decode limit reached.","limit":100,"remaining":0,"resetAt":"2026-08-01T00:00:00.000Z"}}}}}}}}},"/api/report-decode-issue":{"post":{"tags":["Feedback"],"summary":"Report an incorrect decode","description":"Stores a correction request for admin review. Subscriber API keys attach the report to the authenticated client.","operationId":"reportDecodeIssue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDecodeIssueRequest"},"examples":{"correction":{"value":{"vin":"WVWZZZAUZHP507470","expectedManufacturer":"Volkswagen","expectedModel":"Golf","expectedBodyStyle":"Combi","expectedModelYear":"2017","note":"Customer record confirms this is a Golf Variant."}}}}}},"responses":{"200":{"description":"Issue report saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDecodeIssueResponse"},"examples":{"saved":{"value":{"saved":true,"source":"subscriber-client"}}}}}},"400":{"description":"Missing required correction fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid or inactive API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"},"BearerApiKey":{"type":"http","scheme":"bearer"}},"schemas":{"DecodeRequest":{"type":"object","required":["vin"],"properties":{"vin":{"type":"string","minLength":1,"maxLength":64,"example":"WVWZZZAUZHP507470"}}},"DecodeResponse":{"type":"object","required":["report","usage"],"properties":{"report":{"$ref":"#/components/schemas/PublicVehicleReport"},"usage":{"$ref":"#/components/schemas/UsageInfo"}}},"PublicVehicleReport":{"type":"object","additionalProperties":false,"properties":{"vin":{"type":"string"},"wmi":{"type":"string"},"vds":{"type":"string"},"vis":{"type":"string"},"checkDigit":{"type":"string"},"yearCode":{"type":"string"},"plantCode":{"type":"string"},"serialNumber":{"type":"string"},"validFormat":{"type":"boolean"},"manufacturer":{"type":"string"},"model":{"type":"string"},"modelCode":{"type":"string"},"generation":{"type":"string"},"bodyStyle":{"type":"string"},"modelYear":{"type":"string"},"trim":{"type":"string"},"vehicleType":{"type":"string"},"plant":{"type":"string"},"region":{"type":"string"},"possibleBodyStyles":{"type":"array","items":{"type":"string"}},"specs":{"type":"object","additionalProperties":false,"description":"Optional bonus technical data. Fields are returned only when available.","properties":{"engine":{"type":"string"},"fuelType":{"type":"string"},"transmission":{"type":"string"},"driveType":{"type":"string"},"powerKw":{"type":"number"},"displacementCc":{"type":"number"},"batteryCapacityKwh":{"type":"number"},"emissionsStandard":{"type":"string"},"market":{"type":"string"},"plantCountry":{"type":"string"},"plantCity":{"type":"string"}}},"technicalSpecs":{"type":"object","additionalProperties":false,"description":"Optional bonus model-level dimensions and weight. Fields are returned only when available and may represent model/variant-level data.","properties":{"lengthMm":{"type":"number"},"widthMm":{"type":"number"},"heightMm":{"type":"number"},"wheelbaseMm":{"type":"number"},"curbWeightKg":{"type":"number"},"grossWeightKg":{"type":"number"},"groundClearanceMm":{"type":"number"},"cargoVolumeLiters":{"type":"number"},"cargoVolumeMaxLiters":{"type":"number"}}}}},"UsageInfo":{"type":"object","properties":{"limit":{"type":"integer","nullable":true},"remaining":{"type":"integer","nullable":true},"resetAt":{"type":"string","nullable":true,"format":"date-time"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"RateLimitErrorResponse":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"limit":{"type":"integer","nullable":true},"remaining":{"type":"integer","nullable":true},"resetAt":{"type":"string","nullable":true,"format":"date-time"}}}]},"ReportDecodeIssueRequest":{"type":"object","required":["vin","expectedManufacturer","expectedModel","expectedBodyStyle","expectedModelYear","note"],"properties":{"vin":{"type":"string","maxLength":64},"expectedManufacturer":{"type":"string","maxLength":120},"expectedModel":{"type":"string","maxLength":160},"expectedBodyStyle":{"type":"string","maxLength":120},"expectedModelYear":{"type":"string","maxLength":32},"actualReport":{"type":"object","nullable":true,"additionalProperties":true},"note":{"type":"string","maxLength":2000}}},"ReportDecodeIssueResponse":{"type":"object","required":["saved","source"],"properties":{"saved":{"type":"boolean"},"source":{"type":"string"}}}}}}