{ "openapi": "3.1.0", "info": { "title": "CarAPI.dev - Automotive Data API", "description": "Comprehensive automotive data API providing VIN decoding, vehicle history, stolen vehicle checks, valuations, and more. Access reliable vehicle information for your applications.", "version": "1.0.0", "contact": { "name": "CarAPI.dev Support", "url": "https://carapi.dev", "email": "support@carapi.dev" }, "license": { "name": "Proprietary", "url": "https://carapi.dev/terms" }, "x-logo": { "url": "https://carapi.dev/favicon.svg" } }, "servers": [ { "url": "https://api.carapi.dev/v1", "description": "Production API Server" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "VIN", "description": "VIN-related operations including decoding and lookup" }, { "name": "Vehicle History", "description": "Vehicle history and status checks" }, { "name": "Valuation", "description": "Vehicle pricing and valuation" }, { "name": "Listings", "description": "Vehicle marketplace listings" }, { "name": "Media", "description": "Vehicle photos and media" } ], "paths": { "/vin-decode/{vin}": { "get": { "operationId": "decodeVin", "summary": "Decode a VIN", "description": "Decode a Vehicle Identification Number (VIN) to retrieve detailed vehicle specifications including make, model, fuel type, transmission, engine power, and registration date.", "tags": ["VIN"], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (alphanumeric, excluding I, O, Q)", "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "WVWZZZ3CZWE123456" } } ], "responses": { "200": { "description": "Successfully decoded VIN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinDecodeResponse" } } } }, "400": { "description": "Invalid VIN format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "VIN not found in database", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plate-to-vin/{plateNumber}": { "get": { "operationId": "plateToVin", "summary": "Convert license plate to VIN", "description": "Convert a license plate number to its corresponding Vehicle Identification Number (VIN). Requires country code parameter.", "tags": ["VIN"], "parameters": [ { "name": "plateNumber", "in": "path", "required": true, "description": "License plate number", "schema": { "type": "string", "example": "ABC1234" } }, { "name": "country", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code", "schema": { "type": "string", "example": "CZ" } } ], "responses": { "200": { "description": "Successfully converted plate to VIN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlateToVinResponse" } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/stolen-check/{vin}": { "get": { "operationId": "stolenCheck", "summary": "Check if vehicle is stolen", "description": "Check if a vehicle has been reported as stolen in multiple European countries (Slovakia, Czech Republic, Slovenia, Hungary, Romania).", "tags": ["Vehicle History"], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number", "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "WVWZZZ3CZWE123456" } } ], "responses": { "200": { "description": "Stolen status check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StolenCheckResponse" } } } }, "400": { "description": "Invalid VIN format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inspection/{vin}": { "get": { "operationId": "getInspection", "summary": "Get vehicle inspection history", "description": "Retrieve vehicle inspection data including technical inspection (STK) and emissions test (EK) validity dates. Currently supports Slovakia (SK).", "tags": ["Vehicle History"], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number", "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "WVWZZZ3CZWE123456" } }, { "name": "country", "in": "query", "required": true, "description": "Country code (currently only SK supported)", "schema": { "type": "string", "enum": ["SK"], "example": "SK" } } ], "responses": { "200": { "description": "Vehicle inspection data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inspection data not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mileage-history/{vin}": { "get": { "operationId": "getMileageHistory", "summary": "Get vehicle mileage history", "description": "Retrieve historical mileage records for a vehicle to detect odometer rollbacks or inconsistencies.", "tags": ["Vehicle History"], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number", "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "WVWZZZ3CZWE123456" } } ], "responses": { "200": { "description": "Mileage history records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MileageHistoryResponse" } } } }, "400": { "description": "Invalid VIN format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No mileage history found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vehicle-valuation": { "get": { "operationId": "getVehicleValuation", "summary": "Get vehicle valuation", "description": "Get current market valuation for a vehicle based on make, model, and year. Supports 24 countries including EU, UK, US, and others.", "tags": ["Valuation"], "parameters": [ { "name": "make", "in": "query", "required": true, "description": "Vehicle manufacturer name (40 makes supported)", "schema": { "type": "string", "enum": ["acura", "alfa-romeo", "audi", "bmw", "cadillac", "chevrolet", "citroen", "cupra", "dacia", "dodge", "ferrari", "fiat", "ford", "gmc", "honda", "hyundai", "jaguar", "jeep", "kia", "land-rover", "lexus", "mazda", "mercedes-benz", "mg", "mini", "mitsubishi", "nissan", "opel", "peugeot", "porsche", "ram", "renault", "seat", "skoda", "subaru", "suzuki", "tesla", "toyota", "volvo", "vw"], "example": "volkswagen" } }, { "name": "model", "in": "query", "required": true, "description": "Vehicle model name", "schema": { "type": "string", "example": "golf" } }, { "name": "year", "in": "query", "required": true, "description": "Vehicle manufacturing year (1900 to current year + 1)", "schema": { "type": "integer", "minimum": 1900, "example": 2020 } }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code for market-specific valuation", "schema": { "type": "string", "enum": ["CZ", "SK", "DE", "AT", "CH", "FR", "PL", "RO", "HU", "HR", "PT", "BG", "SI", "RS", "NL", "LT", "BE", "ES", "IE", "IT", "UK", "NO", "SE", "US"], "example": "DE" } } ], "responses": { "200": { "description": "Vehicle valuation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValuationResponse" } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Valuation not found for specified vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payments/{vin}": { "get": { "operationId": "calculatePayments", "summary": "Calculate vehicle loan payments", "description": "Calculate monthly payment schedule for a vehicle loan based on price, down payment, loan term, and interest rate.", "tags": ["Valuation"], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number", "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "WVWZZZ3CZWE123456" } }, { "name": "price", "in": "query", "required": true, "description": "Vehicle price", "schema": { "type": "number", "example": 25000 } }, { "name": "downPayment", "in": "query", "required": true, "description": "Down payment amount", "schema": { "type": "number", "example": 5000 } }, { "name": "loanTerm", "in": "query", "required": true, "description": "Loan term in months", "schema": { "type": "integer", "example": 60 } }, { "name": "interestRate", "in": "query", "required": true, "description": "Annual interest rate as percentage", "schema": { "type": "number", "example": 5.5 } } ], "responses": { "200": { "description": "Payment calculation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsResponse" } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/listing": { "get": { "operationId": "searchListings", "summary": "Search vehicle listings", "description": "Search current vehicle listings on the market. Filter by make, model, and year with pagination support.", "tags": ["Listings"], "parameters": [ { "name": "make", "in": "query", "required": false, "description": "Filter by vehicle manufacturer (40 makes supported)", "schema": { "type": "string", "enum": ["acura", "alfa-romeo", "audi", "bmw", "cadillac", "chevrolet", "citroen", "cupra", "dacia", "dodge", "ferrari", "fiat", "ford", "gmc", "honda", "hyundai", "jaguar", "jeep", "kia", "land-rover", "lexus", "mazda", "mercedes-benz", "mg", "mini", "mitsubishi", "nissan", "opel", "peugeot", "porsche", "ram", "renault", "seat", "skoda", "subaru", "suzuki", "tesla", "toyota", "volvo", "vw"], "example": "volkswagen" } }, { "name": "model", "in": "query", "required": false, "description": "Filter by vehicle model", "schema": { "type": "string", "example": "golf" } }, { "name": "year", "in": "query", "required": false, "description": "Filter by manufacturing year", "schema": { "type": "integer", "example": 2020 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return (1-50, default 10)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip for pagination", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of vehicle listings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/photos/{vin}": { "get": { "operationId": "getPhotos", "summary": "Get vehicle photos", "description": "Retrieve available photos for a specific vehicle including exterior, interior, and detail shots.", "tags": ["Media"], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number", "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$", "example": "WVWZZZ3CZWE123456" } } ], "responses": { "200": { "description": "Vehicle photos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotosResponse" } } } }, "400": { "description": "Invalid VIN format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No photos found for this VIN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "query", "name": "token", "description": "API token for authentication. Get your token at https://carapi.dev/dashboard" } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "description": "Error message describing what went wrong", "example": "Invalid VIN format" } } }, "VinDecodeResponse": { "type": "object", "required": ["vin", "specifications", "features"], "properties": { "vin": { "type": "string", "description": "The decoded VIN (uppercase)", "example": "WVWZZZ3CZWE123456" }, "specifications": { "type": "object", "properties": { "make": { "type": "string", "nullable": true, "description": "Vehicle manufacturer", "example": "Volkswagen" }, "model": { "type": "string", "nullable": true, "description": "Vehicle model", "example": "Golf" }, "fuel": { "type": "string", "nullable": true, "description": "Fuel type (petrol, diesel, electric, hybrid)", "example": "petrol" }, "transmission": { "type": "string", "nullable": true, "description": "Transmission type (manual, automatic)", "example": "manual" }, "enginePower": { "type": "string", "nullable": true, "description": "Engine power specification", "example": "110 kW" }, "registrationDate": { "type": "string", "nullable": true, "description": "First registration date (ISO format)", "example": "2020-03-15" } } }, "features": { "type": "array", "items": { "type": "string" }, "description": "List of vehicle features", "example": ["ABS", "ESP", "Air conditioning", "Cruise control"] }, "plateNumber": { "type": "object", "nullable": true, "properties": { "country": { "type": "string", "nullable": true, "example": "CZ" }, "plateNumber": { "type": "string", "nullable": true, "example": "1A2B345" } } } } }, "PlateToVinResponse": { "type": "object", "required": ["plateNumber", "country"], "properties": { "plateNumber": { "type": "string", "description": "The license plate number", "example": "ABC1234" }, "country": { "type": "string", "description": "Country code (uppercase)", "example": "CZ" }, "vin": { "type": "string", "nullable": true, "description": "The corresponding VIN, or null if not found", "example": "WVWZZZ3CZWE123456" } } }, "StolenCheckResponse": { "type": "object", "required": ["vin", "stolen", "countries"], "properties": { "vin": { "type": "string", "description": "The checked VIN", "example": "WVWZZZ3CZWE123456" }, "stolen": { "type": "boolean", "description": "True if vehicle is reported stolen in any checked country", "example": false }, "countries": { "type": "object", "description": "Stolen status per country", "properties": { "sk": { "type": "boolean", "description": "Stolen status in Slovakia" }, "cz": { "type": "boolean", "description": "Stolen status in Czech Republic" }, "si": { "type": "boolean", "description": "Stolen status in Slovenia" }, "hu": { "type": "boolean", "description": "Stolen status in Hungary" }, "ro": { "type": "boolean", "description": "Stolen status in Romania" } } } } }, "InspectionResponse": { "type": "object", "required": ["vin", "country", "inspection"], "properties": { "vin": { "type": "string", "example": "WVWZZZ3CZWE123456" }, "country": { "type": "string", "example": "SK" }, "inspection": { "type": "object", "properties": { "stkValidTo": { "type": "string", "nullable": true, "description": "Technical inspection (STK) validity date", "example": "2025-06-15" }, "ekValidTo": { "type": "string", "nullable": true, "description": "Emissions test (EK) validity date", "example": "2025-06-15" } } } } }, "MileageHistoryResponse": { "type": "object", "required": ["vin", "totalRecords", "mileageHistory"], "properties": { "vin": { "type": "string", "example": "WVWZZZ3CZWE123456" }, "totalRecords": { "type": "integer", "description": "Total number of mileage records", "example": 5 }, "mileageHistory": { "type": "array", "items": { "type": "object", "properties": { "mileage": { "type": "integer", "description": "Recorded mileage in kilometers", "example": 45000 }, "createdAt": { "type": "string", "description": "Date of mileage record (ISO format)", "example": "2023-06-15T10:30:00Z" } } } } } }, "ValuationResponse": { "type": "object", "required": ["make", "model", "year", "valuationPrice", "currency", "country"], "properties": { "make": { "type": "string", "example": "volkswagen" }, "model": { "type": "string", "example": "golf" }, "year": { "type": "integer", "example": 2020 }, "valuationPrice": { "type": "integer", "description": "Estimated market value", "example": 18500 }, "currency": { "type": "string", "description": "Currency code", "example": "EUR" }, "country": { "type": "string", "description": "Market country for valuation", "example": "DE" } } }, "PaymentsResponse": { "type": "object", "required": ["vin", "payments", "loanAmount", "totalPaid", "totalInterest", "monthlyPayment", "currency"], "properties": { "vin": { "type": "string", "example": "WVWZZZ3CZWE123456" }, "payments": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "example": 380.50 }, "currency": { "type": "string", "example": "EUR" }, "frequency": { "type": "string", "enum": ["one-time", "monthly"], "example": "monthly" }, "type": { "type": "string", "enum": ["down-payment", "loan"], "example": "loan" }, "description": { "type": "string", "nullable": true, "example": "Monthly loan payment 1/60" }, "dueDate": { "type": "string", "nullable": true, "description": "Payment due date (YYYY-MM-DD)", "example": "2024-02-15" } } } }, "loanAmount": { "type": "number", "description": "Total loan amount after down payment", "example": 20000 }, "totalPaid": { "type": "number", "description": "Total amount to be paid over loan term", "example": 22830 }, "totalInterest": { "type": "number", "description": "Total interest paid", "example": 2830 }, "monthlyPayment": { "type": "number", "description": "Monthly payment amount", "example": 380.50 }, "currency": { "type": "string", "example": "EUR" } } }, "ListingResponse": { "type": "object", "required": ["listings", "pagination"], "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "vin": { "type": "string", "example": "WVWZZZ3CZWE123456" }, "specifications": { "type": "object", "properties": { "make": { "type": "string", "nullable": true, "example": "Volkswagen" }, "model": { "type": "string", "nullable": true, "example": "Golf" }, "fuel": { "type": "string", "nullable": true, "example": "petrol" }, "transmission": { "type": "string", "nullable": true, "example": "manual" }, "registrationDate": { "type": "string", "nullable": true, "example": "2020-03-15" } } }, "availability": { "type": "object", "properties": { "imagesCount": { "type": "integer", "example": 12 }, "plateNumbersCount": { "type": "integer", "example": 2 }, "historyItemsCount": { "type": "integer", "example": 8 } } } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 10 }, "offset": { "type": "integer", "example": 0 } } } } }, "PhotosResponse": { "type": "object", "required": ["vin", "photos"], "properties": { "vin": { "type": "string", "example": "WVWZZZ3CZWE123456" }, "photos": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Array of photo URLs", "example": ["https://api.carapi.dev/v1/media/encrypted-path-1", "https://api.carapi.dev/v1/media/encrypted-path-2"] } } } } }, "externalDocs": { "description": "Full API Documentation", "url": "https://docs.carapi.dev" } }