{ "openapi": "3.1.0", "info": { "title": "CarsXE API", "description": "CarsXE is a B2B vehicle data API by PiWaves, LLC. It provides vehicle\nspecifications (VIN decoding), market values, vehicle history, recalls,\nlicense plate decoding, vehicle images, plate/VIN image recognition,\nYear Make Model data and OBD code decoding.\n\n## Authentication\n\nMost requests use a CarsXE API key in the `key` query parameter, e.g.\n`https://api.carsxe.com/specs?key=YOUR_API_KEY&vin=...`. Supported endpoints\nalso accept x402 payment without a CarsXE key. Recalls Batch x402 follow-up\nrequests use the scoped `X-CarsXE-Batch-Token` returned at submission.\n\n## Caching\n\nMany endpoints cache upstream results. A cached response may include the\nmessage \"The response is from the cache\".\n", "version": "1.0.0", "contact": { "name": "CarsXE", "url": "https://api.carsxe.com" } }, "servers": [ { "url": "https://api.carsxe.com" } ], "security": [ { "ApiKeyQuery": [] } ], "tags": [ { "name": "Specifications", "description": "VIN decoding and vehicle specifications" }, { "name": "Market Value", "description": "Vehicle market value by VIN" }, { "name": "History", "description": "Vehicle history reports" }, { "name": "Recalls", "description": "Safety recalls by VIN, including bulk batches" }, { "name": "Plate Decoder", "description": "Decode license plates into vehicle data" }, { "name": "Images", "description": "Vehicle images by make/model" }, { "name": "Recognition", "description": "Plate and VIN recognition from images" }, { "name": "Year Make Model", "description": "Year/make/model and OBD code endpoints" }, { "name": "Lien & Theft", "description": "Lien and theft records by VIN" } ], "paths": { "/specs": { "get": { "operationId": "getVehicleSpecs", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Specifications"], "summary": "Vehicle Specifications (VIN decoder)", "description": "Decode a 17-character VIN and return detailed vehicle specifications,\nincluding attributes, colors, equipment and warranties. If the VIN\ncannot be decoded, an International VIN decoding check is run as a\nfallback unless `disableIntVINDecoding=1` is set.\n", "parameters": [ { "$ref": "#/components/parameters/vin" }, { "$ref": "#/components/parameters/format" }, { "name": "deepdata", "in": "query", "required": false, "schema": { "type": "string", "enum": ["1"] }, "description": "Request extra data. Set to `1` to use. Significantly slower than the regular request but retrieves additional data." }, { "name": "disableIntVINDecoding", "in": "query", "required": false, "schema": { "type": "string", "enum": ["1"] }, "description": "Set to `1` to disable the International VIN decoding fallback and return an error instead of a potential partial response." } ], "responses": { "200": { "description": "Vehicle specifications retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecsResponse" }, "example": { "success": true, "input": { "key": "API_KEY", "vin": "WBAFR7C57CC811956" }, "attributes": { "year": "2012", "make": "BMW", "model": "5-Series", "trim": "535i", "style": "SEDAN 4-DR", "type": "Sedan/Saloon", "made_in": "GERMANY", "doors": "4", "fuel_type": "Gasoline", "engine": "3.0L L6 DOHC 24V", "engine_cylinders": "6", "transmission": "6-Speed Manual | 8-Speed Automatic", "drivetrain": "RWD" }, "colors": [ { "category": "Interior", "name": "Black Dakota Leather Interior" }, { "category": "Exterior", "name": "Alpine White" } ], "equipment": { "abs_brakes": "Std.", "air_conditioning": "Std." }, "warranties": [ { "type": "Basic", "miles": "50,000 mile", "months": "48 month" } ], "timestamp": "2025-10-01T22:40:36.374Z" } } } }, "400": { "description": "Missing or invalid VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing vin (vehicle identification number)" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No data found for this VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No data found for this VIN. Try a deep search by setting deepdata=1 in your request" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/international-vin-decoder": { "get": { "operationId": "getInternationalVinDecoder", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Specifications"], "summary": "International VIN Decoder", "description": "Decode a non-US (international) VIN into vehicle attributes.", "parameters": [ { "$ref": "#/components/parameters/vin" } ], "responses": { "200": { "description": "International VIN decoded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "additionalProperties": true }, "attributes": { "type": "object", "description": "Decoded vehicle attributes.", "additionalProperties": true }, "timestamp": { "type": "string" } }, "additionalProperties": true }, "example": { "success": true, "input": { "vin": "WF0MXXGBWM8R43240" }, "attributes": { "vin": "WF0MXXGBWM8R43240", "vid": "1623", "make": "Ford", "model": "Galaxy" }, "timestamp": "2025-04-11T00:05:36.457Z" } } } }, "400": { "description": "Missing VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing vin (vehicle identification number)" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No data found for this VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No data found for this VIN" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/recalls": { "get": { "operationId": "getVehicleRecalls", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Recalls"], "summary": "Vehicle Recalls", "description": "Retrieve open safety recalls for a vehicle by VIN.", "parameters": [ { "$ref": "#/components/parameters/vin" } ], "responses": { "200": { "description": "Recall data retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "additionalProperties": true }, "data": { "type": "object", "description": "Recall report for the VIN.", "additionalProperties": true }, "timestamp": { "type": "string" } }, "additionalProperties": true }, "example": { "success": true, "input": { "key": "API_KEY", "vin": "1C4JJXR64PW696340" }, "data": { "uuid": "d1269d6b-54a2-4bf3-8119-1c8fdb4f0563", "vin": "1C4JJXR64PW696340", "manufacturer": "FCA US LLC", "model_year": "2023" }, "timestamp": "2025-10-03T08:46:03.701Z" } } } }, "400": { "description": "Missing VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing vin (vehicle identification number)" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No recall data found for this VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No data found for this VIN" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/recalls-ymm": { "get": { "operationId": "getRecallsByYmm", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Recalls"], "summary": "Recalls by Year, Make & Model", "description": "Retrieve open safety recalls for a vehicle by year, make, and model \u2014 no VIN required.", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The 4-digit model year (e.g. `2019`)." }, { "name": "make", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The vehicle manufacturer name (e.g. `Toyota`). Case-insensitive." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The vehicle model name (e.g. `Camry`). Case-insensitive." } ], "responses": { "200": { "description": "Recall data retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "properties": { "year": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" } } }, "data": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "model_year": { "type": "string" }, "recall_count": { "type": "integer" }, "has_recalls": { "type": "boolean" }, "recalls": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "timestamp": { "type": "string" } } }, "example": { "success": true, "input": { "year": "2026", "make": "TOYOTA", "model": "COROLLA" }, "data": { "make": "TOYOTA", "model": "COROLLA", "model_year": "2026", "recall_count": 1, "has_recalls": true, "recalls": [ { "nhtsa_campaign_number": "26V110000", "manufacturer": "Toyota Motor Engineering & Manufacturing", "park_it": false, "park_outside": false, "over_the_air_update": false, "report_received_date": "25/02/2026", "component": "EXTERIOR LIGHTING:HEADLIGHTS", "summary": "Toyota is recalling certain 2026 Corolla vehicles.", "consequence": "Incorrectly aimed headlights can reduce driver visibility.", "remedy": "Dealers will replace both front headlight assemblies, free of charge.", "notes": null } ] }, "timestamp": "2026-06-29T12:00:45.786Z" } } } }, "400": { "description": "Missing or invalid year, make, or model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing required parameters" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Feature not available on this plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "This feature is not enabled for your account" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/recalls-batch/submit": { "post": { "operationId": "submitRecallsBatch", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Recalls"], "summary": "Submit a bulk recalls batch", "description": "Submit up to 10,000 VINs for asynchronous recall processing. Provide\nVINs as a JSON array (`vins`), inline CSV text (`csv`), or an HTTPS\nlink to a CSV file (`csvUrl`). Optionally provide a `webhookUrl` that\nCarsXE will POST to when the batch finishes. Poll the status endpoint\nor wait for the webhook, then fetch results.\n\nx402 submissions must use the JSON `vins` array. The `csv` and `csvUrl`\nforms require CarsXE API-key authentication.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vins": { "type": "array", "items": { "type": "string" }, "description": "Array of 17-character VINs (max 10,000 per batch)." }, "csv": { "type": "string", "description": "Inline CSV text containing VINs. Available with CarsXE API-key authentication only; x402 does not accept this form." }, "csvUrl": { "type": "string", "description": "HTTPS link to a CSV file of VINs (max 5 MB) hosted on a supported storage provider (e.g. S3, GCS, Firebase, Dropbox). Available with CarsXE API-key authentication only; x402 does not accept this form." }, "webhookUrl": { "type": "string", "description": "HTTPS URL for a customer webhook. CarsXE POSTs a JSON payload when the batch finishes. Must be a valid HTTPS URL allowed by CarsXE validation rules." } } }, "example": { "vins": ["1HGBH41JXMN109186", "5YJSA1E26HF000001"], "webhookUrl": "https://example.com/webhooks/carsxe-recalls" } } } }, "responses": { "202": { "description": "Batch accepted and queued for processing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "batchId": { "type": "string" }, "status": { "type": "string" }, "totalVins": { "type": "integer" }, "processedVins": { "type": "integer" }, "batchToken": { "type": "string", "description": "Opaque batch-scoped credential returned only for x402 submissions. Send it in X-CarsXE-Batch-Token on follow-up requests." } }, "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true }, "example": { "success": true, "data": { "batchId": "brb_mnablbn7_wvbaqv", "status": "uploading", "totalVins": 3, "processedVins": 0 }, "message": "Batch submitted and queued for processing. Poll the status endpoint or wait for the webhook." } } } }, "400": { "description": "Invalid request body \u2014 missing VINs, invalid VINs, more than 10,000 VINs, invalid `webhookUrl`, or a `csvUrl` that is invalid / not allowed / too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingVins": { "value": { "success": false, "message": "Request body must include at least one of: \"vins\" (non-empty array), \"csv\" (text), or \"csvUrl\" (https link to a CSV) with valid 17-character VINs." } }, "invalidVin": { "value": { "success": false, "message": "One or more VINs are invalid. Each VIN must be exactly 17 characters." } }, "tooManyVins": { "value": { "success": false, "message": "Maximum 10,000 VINs per batch. Split your request into multiple batches." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "405": { "description": "Method not allowed (only POST is accepted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Only POST allowed. Send JSON body with \"vehicles\" array." } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Could not download the CSV from `csvUrl`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Could not download the CSV from csvUrl. Check the link and try again." } } } } } } }, "/v1/recalls-batch/status": { "get": { "security": [ { "ApiKeyQuery": [] }, { "RecallsBatchToken": [] } ], "operationId": "getRecallsBatchStatus", "tags": ["Recalls"], "summary": "Get bulk recalls batch status", "description": "Check the processing status of a previously submitted batch.", "parameters": [ { "$ref": "#/components/parameters/batchId" }, { "$ref": "#/components/parameters/recallsBatchToken" } ], "responses": { "200": { "description": "Batch status retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "batchId": { "type": "string" }, "numericBatchId": { "type": "integer" }, "status": { "type": "string" }, "totalVins": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "success": true, "data": { "batchId": "brb_mnablbn7_wvbaqv", "numericBatchId": 200426, "status": "completed", "totalVins": 3 } } } } }, "400": { "description": "Missing batchId parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing batchId parameter" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Batch not found or not accessible with this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Batch not found or you do not have access to this batch." } } } } } } }, "/v1/recalls-batch/results": { "get": { "security": [ { "ApiKeyQuery": [] }, { "RecallsBatchToken": [] } ], "operationId": "getRecallsBatchResults", "tags": ["Recalls"], "summary": "Get bulk recalls batch results", "description": "Fetch the per-VIN recall results of a completed batch as JSON.", "parameters": [ { "$ref": "#/components/parameters/batchId" }, { "$ref": "#/components/parameters/recallsBatchToken" } ], "responses": { "200": { "description": "Batch results retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "job": { "type": "object", "additionalProperties": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "vin": { "type": "string" }, "hasRecalls": { "type": "boolean" }, "recallCount": { "type": "integer" }, "recalls": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } } } }, "additionalProperties": true }, "example": { "success": true, "data": { "job": { "batchId": "brb_mnablbn7_wvbaqv", "numericBatchId": 200426, "status": "completed" }, "results": [ { "vin": "1HGBH41JXMN109186", "hasRecalls": true, "recallCount": 1 }, { "vin": "5YJSA1E26HF000001", "hasRecalls": false, "recallCount": 0 } ] } } } } }, "400": { "description": "Missing batchId parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing batchId parameter" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Batch not found or not accessible with this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Batch not found or you do not have access to this batch." } } } }, "409": { "description": "Batch processing is not yet complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Batch processing is not yet complete. Check status and try again later." } } } } } } }, "/v1/recalls-batch/download": { "get": { "security": [ { "ApiKeyQuery": [] }, { "RecallsBatchToken": [] } ], "operationId": "downloadRecallsBatchResults", "tags": ["Recalls"], "summary": "Download bulk recalls batch results", "description": "Download the results of a completed batch as CSV.", "parameters": [ { "$ref": "#/components/parameters/batchId" }, { "$ref": "#/components/parameters/recallsBatchToken" } ], "responses": { "200": { "description": "CSV results file.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Missing batchId parameter." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Batch not found or not accessible with these credentials." }, "409": { "description": "Batch processing is not yet complete." } } } }, "/platedecoder": { "get": { "operationId": "decodePlate", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Plate Decoder"], "summary": "License Plate Decoder (v1)", "description": "Decode a license plate into vehicle data. Internally proxies to the v2\nplate decoder. The `state` parameter accepts a two-letter US state\ncode, Australian state, or one of the legacy country codes `BR`, `UK`,\n`IR`, `IT`, `ES`, `IND`, `MX`, `NZ`.\n", "parameters": [ { "name": "plate", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The vehicle registration number or license plate number." }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The two letter state code (US) such as `CA` or `NY`, Australian state, or Brazil `BR`, United Kingdom `UK`, Ireland `IR`, Italy `IT`, Spain `ES`, India `IND`, Mexico `MX`, New Zealand `NZ`." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country code, e.g. Australia `AU`. Optional for `US`." }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "Plate decoded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "additionalProperties": true }, "vin": { "type": "string" } }, "additionalProperties": true }, "example": { "success": true, "input": { "plate": "7XER187", "state": "CA", "country": "US" }, "vin": "3KPFK4A78HE103497", "assembly": "Mexico", "Description": "Kia Forte LX", "BodyStyle": "Sedan", "RegistrationYear": "2017", "EngineSize": "2.0L I4 MPI", "CarMake": "Kia", "CarModel": "Forte" } } } }, "400": { "description": "Missing plate or state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingPlate": { "value": { "success": false, "message": "Missing vehicle registration number or license plate number" } }, "missingState": { "value": { "success": false, "message": "Missing 2 letter state code" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No data found for this plate (passed through from the v2 decoder).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Could not fetch data" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "502": { "description": "Upstream plate decoder request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Could not fetch data" } } } }, "504": { "description": "Upstream plate decoder request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Request timed out. Please try again." } } } } } } }, "/v1/us-platedecoder": { "get": { "operationId": "decodeUsPlate", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Plate Decoder"], "summary": "US Vehicle Plate Decoder", "description": "Look up a US vehicle by license plate number and state. Returns the\nVIN, year, make, model, trim, engine, body style, transmission, drive\ntype, fuel type and exterior color. Optionally decodes the VIN to\ninclude the full vehicle specifications object. Accepts plates from all\n50 US states, the District of Columbia (DC) and Puerto Rico (PR).\n\nThis endpoint is **not** available on the free Sandbox tier.\n", "parameters": [ { "name": "plate", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The vehicle registration number or license plate number." }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter abbreviation for one of the 50 US states, the District of Columbia (`DC`), or Puerto Rico (`PR`)." }, { "name": "decodeVIN", "in": "query", "required": false, "schema": { "type": "string", "enum": ["true", "1"] }, "description": "Set to `true` or `1` to decode the resolved VIN and include a `vehicle_specs` object in the response (identical in shape to the Specifications endpoint response)." } ], "responses": { "200": { "description": "Plate decoded successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "properties": { "plate": { "type": "string" }, "state": { "type": "string" } }, "additionalProperties": true }, "vin": { "type": "string" }, "year": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "trim": { "type": "string" }, "description": { "type": "string" }, "engine_size": { "type": "string" }, "body_style": { "type": "string" }, "transmission": { "type": "string" }, "drive_type": { "type": "string" }, "fuel_type": { "type": "string" }, "color": { "type": "string" }, "vehicle_specs": { "$ref": "#/components/schemas/SpecsResponse", "description": "Full vehicle specifications (only present when `decodeVIN=true`)." } }, "additionalProperties": true }, "example": { "success": true, "input": { "plate": "H37SFS", "state": "NJ" }, "vin": "1GNSCGKC0JR318026", "year": "2018", "make": "Chevrolet", "model": "Suburban", "trim": "LS", "description": "2018 Chevrolet Suburban", "engine_size": "5.3L V8 OHV 16V", "body_style": "SUV", "transmission": "Automatic", "drive_type": "RWD", "fuel_type": "Flexible-Fuel", "color": "Black" } } } }, "400": { "description": "Missing plate, state, or API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingPlate": { "value": { "success": false, "message": "Missing vehicle registration number or license plate number" } }, "missingState": { "value": { "success": false, "message": "Missing 2 letter state code" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No data found for this plate/state combination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Could not fetch data" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/lien-theft": { "get": { "operationId": "getLienTheft", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Lien & Theft"], "summary": "Lien & Theft records", "description": "Check a VIN for active lien and theft records (US).", "parameters": [ { "$ref": "#/components/parameters/vin" } ], "responses": { "200": { "description": "Lien/theft data retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string" }, "year": { "type": "integer" }, "make": { "type": "string" }, "model": { "type": "string" }, "type": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "trim_data": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "example": { "success": true, "input": { "vin": "2C3CDXFG1FH762860" }, "timestamp": "2025-12-07T20:32:11.027Z", "year": 2015, "make": "DODGE", "model": "Charger", "type": "CAR", "events": [ { "event": "Recovered Theft", "location": "OH", "details_list": ["The vehicle is reported to be an Recovered Theft."] } ] } } } }, "400": { "description": "Missing or invalid VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingVin": { "value": { "success": false, "message": "Missing vin (vehicle identification number)" } }, "wrongLength": { "value": { "success": false, "message": "Wrong VIN length, must be 17 characters" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No lien or theft data found for this VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No lien or theft data found for this VIN" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" } } } }, "/images": { "get": { "operationId": "getVehicleImages", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Images"], "summary": "Vehicle Images", "description": "Retrieve images of a vehicle by make, model and other filters.", "parameters": [ { "name": "make", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The vehicle make." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The vehicle model." }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The vehicle year." }, { "name": "trim", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The vehicle trim." }, { "name": "color", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The vehicle color." }, { "name": "transparent", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Prioritize images with transparent background. Defaults to `true`." }, { "name": "angle", "in": "query", "required": false, "schema": { "type": "string", "enum": ["front", "side", "back"] }, "description": "The angle to show the car in." }, { "name": "photoType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["interior", "exterior", "engine"] }, "description": "Request images of the interior, exterior or engine. Can only be used in conjunction with year, make, model and trim query params." }, { "name": "size", "in": "query", "required": false, "schema": { "type": "string", "enum": ["Small", "Medium", "Large", "Wallpaper", "All"] }, "description": "Request images of a given size. Defaults to all sizes." }, { "name": "license", "in": "query", "required": false, "schema": { "type": "string", "enum": ["Public", "Share", "ShareCommercially", "Modify", "ModifyCommercially"] }, "description": "Filter images by license type. Leave blank to return all images." }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "Images retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "mime": { "type": "string" }, "link": { "type": "string" }, "contextLink": { "type": "string" }, "height": { "type": "integer" }, "width": { "type": "integer" }, "byteSize": { "type": "integer" }, "thumbnailLink": { "type": "string" }, "accentColor": { "type": "string" } }, "additionalProperties": true } }, "query": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "example": { "success": true, "images": [ { "mime": "image/png", "link": "https://bit.ly/34tpueu", "contextLink": "https://www.mariettatoyota.com/toyota-tacoma/", "height": 272, "width": 1000, "byteSize": 56662, "thumbnailLink": "https://bit.ly/34xewVr", "accentColor": "B51617" } ], "query": { "year": "2018", "make": "toyota", "model": "tacoma", "color": "blue", "format": "json" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No images found for this query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No images found" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "description": "Missing make/model, or the image search failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingMakeModel": { "value": { "success": false, "message": "Please supply a make and model. Visit https://carsxe.com/docs for more information" } }, "cannotAccessInternet": { "value": { "success": false, "message": "Cannot access the internet at this time" } } } } } } } } }, "/marketvalue": { "get": { "operationId": "getMarketValue", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Market Value"], "summary": "Vehicle Market Value (v1)", "description": "Get the market value of a vehicle by VIN, including retail, trade-in and auction values.", "parameters": [ { "$ref": "#/components/parameters/vin" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "Market value retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "vin": { "type": "string" }, "retail": { "type": "string", "description": "Retail price of the vehicle." }, "tradeIn": { "type": "string", "description": "The trade in price of the vehicle." }, "roughTradeIn": { "type": "string" }, "averageTradeIn": { "type": "string" }, "loanValue": { "type": "string" }, "msrp": { "type": "string" }, "tradeInValues": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "auctionValues": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "example": { "retail": "16075", "tradeIn": "13575", "roughTradeIn": "10250", "averageTradeIn": "12050", "loanValue": "12225", "uid": 1172227, "msrp": "52250", "tradeInValues": [ { "date": "2018-08-01T00:00:00.000Z", "value": "13575" }, { "date": "2018-07-01T00:00:00.000Z", "value": "13600" } ], "auctionValues": { "lowAuctionValue": 9050, "averageAuctionValue": 11925, "highAuctionValue": 14825, "dateRange": "8/6/2018 - 8/12/2018" } } } } }, "400": { "description": "Missing VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing vin (vehicle identification number)" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No data found for this VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No data found for this VIN" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/history": { "get": { "operationId": "getVehicleHistory", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["History"], "summary": "Vehicle History", "description": "Retrieve a vehicle history report by VIN, including title, brand, junk/salvage and insurance records.", "parameters": [ { "$ref": "#/components/parameters/vin" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "History report retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "vin": { "type": "string" }, "junkAndSalvageInformation": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "insuranceInformation": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "brandsRecordCount": { "type": "number" }, "brandsInformation": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "vinChanged": { "type": "boolean" }, "currentTitleInformation": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "historyInformation": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Missing or invalid VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingVin": { "value": { "success": false, "message": "Missing vin (vehicle identification number)" } }, "wrongLength": { "value": { "success": false, "message": "Wrong VIN length, must be 17 characters" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "This API key has been blocked for the History API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "This API key has been blocked, please contact support if you believe this is an error." } } } }, "404": { "description": "No history data found for this VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No data found for this VIN" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/platerecognition": { "post": { "operationId": "recognizePlate", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Recognition"], "summary": "Plate Image Recognition", "description": "Extract a license plate number from an image of a vehicle. Send a JSON body containing an `image_url` field with a URL to the image.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["image_url"], "properties": { "image_url": { "type": "string", "description": "URL to an image of a vehicle's license plate." } } }, "example": { "image_url": "https://example.com/car-photo.jpg" } } } }, "responses": { "200": { "description": "Plate recognized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "plate": { "type": "string" }, "box": { "type": "object", "additionalProperties": true }, "region": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "processing_time": { "type": "number" } }, "additionalProperties": true }, "example": { "success": true, "message": "", "results": [ { "box": { "xmin": 2045, "ymin": 1400, "xmax": 2732 }, "plate": "9djc652", "region": { "code": "us-ca", "score": 0.849 } } ], "processing_time": 117.822 } } } }, "400": { "description": "Missing image URL in the request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing upload URL" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No plate could be recognized in the image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No plates detected in image" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "description": "Plate recognition service error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Could not get information at this time" } } } } } } }, "/v1/vinocr": { "post": { "operationId": "vinOcr", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Recognition"], "summary": "VIN OCR", "description": "Extract a VIN from a photo. Send a JSON body containing an `image_url` field with either a URL to an image or a base64-encoded image string.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["image_url"], "properties": { "image_url": { "type": "string", "description": "URL to an image, or the base64 string of the image." } } }, "example": { "image_url": "https://example.com/vin-plate.jpg" } } } }, "responses": { "200": { "description": "VIN extracted from the image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "vin": { "type": "string" }, "box": { "type": "object", "additionalProperties": true }, "confidence": { "type": "number" }, "candidates": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "example": { "success": true, "vin": "JHLRD77874C026456", "box": { "xmin": 257, "xmax": 1673, "ymin": 635, "ymax": 793 }, "confidence": 0.9834251403808594, "candidates": [ { "vin": "JHLRD77874C026456", "confidence": 0.9834251403808594 } ] } } } }, "400": { "description": "Missing API key, missing image, invalid image data, image processing failure, or no text detected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingKey": { "value": { "success": false, "message": "Missing API key" } }, "missingImage": { "value": { "success": false, "message": "Missing image data" } }, "invalidImage": { "value": { "success": false, "message": "Invalid image data format. Must be a valid URL or base64 encoded string." } }, "noText": { "value": { "success": false, "message": "No text detected in the image" } } } } } }, "401": { "description": "User with this API key is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "User with this API key is not active. To activate update your billing on https://carsxe.com/dashboard/billing" } } } }, "404": { "description": "API key not found, or no valid VIN found in the image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "userNotFound": { "value": { "success": false, "message": "User with this API key was not found or the API key is disabled" } }, "noVin": { "value": { "success": false, "message": "No valid VIN candidates found in the image" } } } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" } } } }, "/v1/ymm": { "get": { "operationId": "getYearMakeModel", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Year Make Model"], "summary": "Year Make Model", "description": "Look up vehicle data by year, make and model (and optionally trim) without a VIN.", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The manufacturing year of the vehicle (numeric, between 1900 and the current model year plus one)." }, { "name": "make", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The manufacturer of the vehicle (e.g., Toyota, Ford, BMW)." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The specific model of the vehicle (e.g., Camry, F-150, X5)." }, { "name": "trim", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The vehicle trim (e.g., XLE, XSE)." }, { "name": "allTrimOptions", "in": "query", "required": false, "schema": { "type": "string", "enum": ["1"] }, "description": "Return all trim options available for the year, make and model. Set to `1` to use." } ], "responses": { "200": { "description": "Vehicle matched.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "bestMatch": { "type": "object", "additionalProperties": true }, "trimOptions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "input": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string" } }, "additionalProperties": true }, "example": { "bestMatch": { "make": "Toyota", "model": "Camry", "year": "2023", "name": "XLE 4dr Sedan (3.5L 6cyl 8A)" }, "trimOptions": [], "success": true, "input": { "year": "2023", "make": "Toyota", "model": "Camry", "trim": "XLE" }, "timestamp": "2024-03-19T12:00:00.000Z" } } } }, "400": { "description": "Missing or invalid year, make or model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "value": { "success": false, "message": "Missing year, make, or model" } }, "invalidYear": { "value": { "success": false, "message": "Invalid year. Provide a numeric year between 1900 and the current model year plus one." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No vehicle matched the specified year, make and model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No vehicle found matching the specified year, make, and model. Try case-sensitive search such as \"2023 Toyota Camry\"" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "description": "Could not fetch data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Could not fetch data" } } } } } } }, "/v1/ymm-options": { "get": { "operationId": "getYearMakeModelOptions", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Year Make Model"], "summary": "Year Make Model Options", "description": "Populate Year, Make, Model, and Variant dropdown menus. Each response returns exactly one layer. `dimension` is optional \u2014 when omitted, the response shape is inferred from `make`/`model`/`year`. Billing: most calls cost 1 unit. `dimension=variants` with `year` + `make` (no `model`) costs 1 unit per model; the response includes `modelCount`. Required filters help you get better, more relevant results. `year`, `make`, and `model` can be combined for reversed lookups (e.g. years for a given make+model).", "parameters": [ { "name": "dimension", "in": "query", "required": false, "schema": { "type": "string", "enum": ["years", "makes", "models", "trims", "variants"] }, "description": "Return exactly this array when required filters are present. If omitted, the response is inferred automatically from `make`/`model`/`year`." }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to a specific manufacturing year. Required when filtering by `model` without `make`." }, { "name": "make", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to a specific manufacturer (e.g., Toyota, Ford, Lexus). Required for `dimension=models`." }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to a specific model (e.g., Camry, F-150, LX). Required for `dimension=trims` and for `dimension=variants` unless both `year` and `make` are set." }, { "name": "trim", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional substring filter on trim names. Only applied when querying `dimension=trims` or `dimension=variants`." } ], "responses": { "200": { "description": "Distinct values for the requested (or inferred) dimension(s).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "additionalProperties": true }, "message": { "type": "string", "description": "Optional guidance when the returned layer differs from the requested dimension or when explaining how to get better results." }, "years": { "type": "array", "items": { "type": "integer" } }, "makes": { "type": "array", "items": { "type": "string" } }, "models": { "type": "array", "items": { "type": "string" } }, "trims": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "string" } }, "modelCount": { "type": "integer", "description": "Present only for bulk variants (`dimension=variants` + year + make, no model). Number of distinct models, which is also the amount billed \u2014 except a zero-match query, which returns 0 but still bills a minimum of 1 unit." } }, "additionalProperties": true }, "examples": { "variants": { "summary": "make+model given -> variants only", "value": { "success": true, "input": { "year": 2026, "make": "Toyota", "model": "Tacoma" }, "variants": [ "Tacoma Limited", "Tacoma SR", "Tacoma SR5", "Tacoma TRD Off-Road", "Tacoma TRD PreRunner", "Tacoma TRD Pro", "Tacoma TRD Sport", "Tacoma Trailhunter" ] } }, "modelsForMakeOnly": { "summary": "make given, no model -> models only (one layer per response)", "value": { "success": true, "input": { "year": 2026, "make": "Toyota" }, "models": ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"] } }, "variantsForYearAndModel": { "summary": "year+model given, no make -> variants only", "value": { "success": true, "input": { "year": 2026, "model": "Tacoma" }, "variants": ["Tacoma Limited", "Tacoma SR", "Tacoma SR5", "Tacoma TRD Pro"] } }, "variantsForYearAndMake": { "summary": "dimension=variants with year+make -> billed per model (modelCount)", "value": { "success": true, "input": { "dimension": "variants", "year": 2025, "make": "Lexus" }, "variants": ["ES 250", "ES 300h", "GX 550 Premium", "IS 300", "LX 600 Premium", "RX 350"], "modelCount": 6 } }, "variantsFallbackToModels": { "summary": "dimension=variants with make only (no year) -> models + message", "value": { "success": true, "input": { "dimension": "variants", "make": "Toyota" }, "message": "To receive variants, include a model filter with this make. Models are returned instead.", "models": ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"] } }, "yearsForMakeModel": { "summary": "Reversed combination: dimension=years filtered by make+model", "value": { "success": true, "input": { "dimension": "years", "make": "Lexus", "model": "TX" }, "years": [2026, 2025, 2024] } } } } } }, "400": { "description": "Invalid dimension, invalid year, missing required filters, or model without make/year.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidDimension": { "value": { "success": false, "message": "Invalid dimension. Must be one of: years, makes, models, trims, variants." } }, "invalidYear": { "value": { "success": false, "message": "Invalid year. Provide a numeric year between 1900 and the current model year plus one." } }, "missingMakeForModels": { "value": { "success": false, "message": "A make filter is required to list models. Add make=... to get better results." } }, "missingMakeOrModelForTrimsVariants": { "value": { "success": false, "message": "Trims and variants require a make or model filter. Add make=... or model=... to get better results." } }, "missingYearWhenModelWithoutMake": { "value": { "success": false, "message": "When filtering by model without make, a year filter is required. Add year=... to get better results." } }, "missingMakeWhenModelAmbiguous": { "value": { "success": false, "message": "This model name appears under multiple makes. Add make=... together with year and model to get better results." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "description": "Could not fetch data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Could not fetch data" } } } } } } }, "/obdcodesdecoder": { "get": { "operationId": "decodeObdCode", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Year Make Model"], "summary": "OBD Codes Decoder", "description": "Decode an OBD-II diagnostic trouble code (e.g. P0115).", "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The OBD code." } ], "responses": { "200": { "description": "OBD code decoded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "diagnosis": { "type": "string" }, "date": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true }, "example": { "success": true, "diagnosis": "Engine Coolant Temperature Circuit Malfunction", "date": "2020-07-04T21:44:39.767Z", "code": "P0115" } } } }, "400": { "description": "Missing OBD code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Missing OBD code" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The OBD code could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Could not find code P9999" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" } } } }, "/v2/platedecoder": { "get": { "operationId": "decodePlateV2", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Plate Decoder"], "summary": "License Plate Decoder (v2)", "description": "Decode a license plate into vehicle data across 60+ supported\ncountries. `country` is an ISO 3166-1 alpha-2 code (optional for `US`).\n`state` is required for `US`, `AU` and `CA`. For Pakistan (`PK`) a\n`district` is also required for the Khyber-Pakhtunkhwa province.\n\nFor Spain (`ES`), set `require_vin=true` to always include a VIN.\nAdditional charges apply: when `require_vin=true`, the request is\nbilled 2x and usage counts 2x.\n", "parameters": [ { "name": "plate", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The vehicle registration number or license plate number." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country code such as `AU` for Australia or `ZA` for South Africa. Optional for `US`." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The two letter state code (US) such as `CA` or `NY`, an Australian state (e.g. `NSW`, `VIC`), or a Canadian province (e.g. `ON`). Required only for `US`, `AU` and `CA`." }, { "name": "district", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The district of the vehicle registration number. Required for Pakistan (`PK`) plates registered in the Khyber-Pakhtunkhwa province." }, { "name": "require_vin", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only supported when `country=ES`. Set to `true` to always include a VIN. The request is billed 2x and usage counts 2x." } ], "responses": { "200": { "description": "Plate decoded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "additionalProperties": true }, "description": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "trim": { "type": "string" }, "vin": { "type": "string" }, "year": { "type": "string" } }, "additionalProperties": true }, "example": { "success": true, "input": { "plate": "7XER187", "state": "CA", "country": "US" }, "description": "Kia Forte LX", "make": "Kia", "model": "Forte", "trim": "LX", "vin": "3KPFK4A78HE103497", "style": "Sedan 4D", "year": "2017", "assembly": "Mexico", "fuel_type": "Gasoline", "color": "White", "body_style": "Sedan", "engine_size": "2.0L I4 MPI", "drive_type": "FWD", "transmission": "Automatic" } } } }, "400": { "description": "Missing plate, or `require_vin` used with a country other than ES.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingPlate": { "value": { "success": false, "message": "Missing vehicle registration number or license plate number" } }, "requireVin": { "value": { "success": false, "message": "The require_vin parameter is only supported when country=ES." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Invalid state/country/district, or no data found for this plate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidState": { "value": { "success": false, "message": "Invalid state or country code." } }, "invalidDistrict": { "value": { "success": false, "message": "Invalid district" } }, "notFound": { "value": { "success": false, "message": "Plate searches for this country have been disabled, or No data found for this plate" } } } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" } } } }, "/v2/marketvalue": { "get": { "operationId": "getMarketValueV2", "security": [ { "ApiKeyQuery": [] }, { "X402Payment": [] }, {} ], "tags": ["Market Value"], "summary": "Vehicle Market Value (v2)", "description": "Get detailed market values for a VIN, including wholesale, retail and trade-in values across condition tiers, with optional adjustments for US state, mileage and condition.", "parameters": [ { "$ref": "#/components/parameters/vin" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The US state of the vehicle to get the market value for." }, { "name": "mileage", "in": "query", "required": false, "schema": { "type": "number" }, "description": "The current mileage of the vehicle used to adjust the market value. Must be a valid numeric value." }, { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "enum": ["excellent", "clean", "average", "rough"] }, "description": "The overall condition of the vehicle." } ], "responses": { "200": { "description": "Market value retrieved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string" }, "input": { "type": "object", "additionalProperties": true }, "publish_date": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "model_year": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "series": { "type": "string" }, "style": { "type": "string" }, "class_name": { "type": "string" }, "whole_xclean": { "type": "object", "additionalProperties": true }, "whole_clean": { "type": "object", "additionalProperties": true }, "whole_avg": { "type": "object", "additionalProperties": true }, "whole_rough": { "type": "object", "additionalProperties": true }, "retail_xclean": { "type": "object", "additionalProperties": true }, "retail_clean": { "type": "object", "additionalProperties": true }, "retail_avg": { "type": "object", "additionalProperties": true }, "retail_rough": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "example": { "uid": "FDE60872", "input": { "vin": "WBAFR7C57CC811956", "country": "US" }, "publish_date": "4/8/2025", "state": "NT", "country": "US", "model_year": "2012", "make": "BMW", "model": "5-Series", "series": "535i", "style": "4D Sedan", "class_name": "Luxury Car", "whole_clean": { "base_whole_clean": 5300, "mileage_whole_clean": 0, "add_deduct_whole_clean": 0, "regional_whole_clean": 0 }, "retail_clean": { "base_retail_clean": 9325, "mileage_retail_clean": 0, "add_deduct_retail_clean": 0, "regional_retail_clean": 0 } } } } }, "400": { "description": "Missing/invalid VIN, mileage or condition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingVin": { "value": { "success": false, "message": "Missing vin (vehicle identification number)" } }, "wrongLength": { "value": { "success": false, "message": "Wrong VIN length, must be 17 characters" } }, "invalidCondition": { "value": { "success": false, "message": "Invalid condition. Available conditions: excellent, clean, average, rough" } }, "invalidMileage": { "value": { "success": false, "message": "Invalid mileage. Must be a number" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No data found for this VIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "No data found for this VIN" } } } }, "429": { "$ref": "#/components/responses/UsageLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "description": "Upstream market value provider is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Cannot access the internet at this time" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "key", "description": "Your CarsXE API key, passed as the `key` query parameter." }, "X402Payment": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "x402 payment proof for supported operations. Start without a CarsXE key to receive HTTP 402 payment requirements, then retry the identical request with the payment header produced by your x402 client. CarsXE also accepts the legacy X-PAYMENT header." }, "RecallsBatchToken": { "type": "apiKey", "in": "header", "name": "X-CarsXE-Batch-Token", "description": "Batch-scoped token returned by an x402 Recalls Batch submission." } }, "parameters": { "vin": { "name": "vin", "in": "query", "required": true, "schema": { "type": "string", "minLength": 17, "maxLength": 17 }, "description": "The 17 character long vehicle identification number." }, "format": { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["json", "xml"], "default": "json" }, "description": "The format of the response. One of `json` or `xml`." }, "batchId": { "name": "batchId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The batch ID returned from the submit endpoint." }, "recallsBatchToken": { "name": "X-CarsXE-Batch-Token", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Batch-scoped token returned by an x402 submit call. Use this instead of the key query parameter for status, results, and download requests." } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "message": { "type": "string" } }, "required": ["success", "message"], "additionalProperties": true }, "UsageLimitError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "usage": { "type": "object", "properties": { "current": { "type": "number", "description": "Current usage in the billing period." }, "limit": { "type": "number", "description": "Included quota for the billing period." }, "remaining": { "type": "number", "description": "Remaining included quota." } } } } } ] }, "SuccessEnvelope": { "type": "object", "description": "Generic success envelope. Endpoint-specific payload fields appear at the top level alongside these common fields.", "properties": { "success": { "type": "boolean" }, "input": { "type": "object", "description": "Echo of the input parameters specified by the query.", "additionalProperties": true }, "timestamp": { "type": "string" } }, "additionalProperties": true }, "SpecsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "attributes": { "type": "object", "description": "A map of specifications about the VIN (year, make, model, trim, style, type, size, category, made_in, doors, fuel_type, engine, transmission, drivetrain, dimensions, pricing and more).", "additionalProperties": true }, "colors": { "type": "array", "description": "Available color options based on the vehicle's year, make and model.", "items": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } }, "equipment": { "type": "object", "description": "Equipment details based on the vehicle's year, make and model.", "additionalProperties": true }, "warranties": { "type": "array", "description": "Standard vehicle warranties by type, miles and months.", "items": { "type": "object", "properties": { "type": { "type": "string" }, "miles": { "type": "string" }, "months": { "type": "string" } }, "additionalProperties": true } }, "deepdata": { "type": "object", "description": "More information on the vehicle from the deep data search (present when `deepdata=1`).", "additionalProperties": true } } } ] } }, "responses": { "Unauthorized": { "description": "Missing API key, unknown/disabled API key, or inactive account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingKey": { "value": { "success": false, "message": "Missing API key" } }, "userNotFound": { "value": { "success": false, "message": "User with this API key was not found or the API key is disabled" } }, "userNotActive": { "value": { "success": false, "message": "User with this API key is not active. To activate update your billing on https://carsxe.com/dashboard/billing" } } } } } }, "UsageLimitExceeded": { "description": "API usage limit exceeded for the current billing period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageLimitError" }, "example": { "success": false, "message": "API usage limit exceeded", "usage": { "current": 1000, "limit": 1000, "remaining": 0 } } } } }, "InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Internal server error" } } } } } } }