# Documentation ## Documentation URL: /docs Welcome to CarsXE API's documentation. Learn everything there is to know about CarsXE API and integrate CarsXE into your product. Getting started To get started, sign in or create an account and grab an API key, then read about how to make requests for the resources you need to access using our HTTP APIs. Guides Quickstart Get a quick start integrating the API into your application. Products Explore the full suite of vehicle data APIs available. Organizations Share API access with your team using roles and organization API keys. Errors Read about the different types of errors returned by the API. Rate Limits & Quotas Understand monthly quotas, 429 responses, and overage billing. Agents & AI Get an API key, read docs, and make calls — all from inside your AI agent. --- ## Get Started URL: /docs/get-started Everything you need to start building with the CarsXE Vehicle Data API. CarsXE is a REST API for vehicle data. Pass an API key and a VIN (or plate), get structured JSON back. No SDKs required, no complex auth — just HTTP. What's available | API | What it returns | |---|---| | VIN Decoder | Make, model, year, engine, trim, standard equipment | | Market Value | Retail, trade-in, and auction estimates | | Vehicle History | Title events, salvage, junk, and insurance records | | Recalls | Open safety recalls by VIN | | Plate Decoder | VIN lookup from a license plate (50+ countries) | | Vehicle Images | Photos by make, model, and year | | Recognition | VIN and plate extraction from images | | Year Make Model | Year/make/model vehicle search and OBD-II code decoder | | Lien & Theft | Active liens and stolen vehicle status | All endpoints use simple GET requests with query parameters. A handful of image/recognition endpoints use POST with a JSON body. API Keys Your API key lives in the developer dashboard. Sign in above to copy it directly, or open the dashboard to manage usage and rotate keys. Keep it secret. Store your key in an environment variable — never hardcode it or commit it to source control. Authentication Every request requires your key as the key query parameter — no headers, tokens, or OAuth flows. That's it. A 401 means the key is missing or wrong. A 403 means your plan doesn't include that endpoint. Quickstart Decode your first VIN — swap in your key and run it: A 200 with JSON vehicle specs means you're live. From here, explore the API Reference or check the Errors guide for handling failures. --- ## Guides URL: /docs/guides Cross-cutting topics — rate limits, error handling, organizations, and AI agent integration. Cross-cutting guides that apply across all CarsXE API products. --- ## Agents & AI URL: /docs/guides/agents Everything you need to use CarsXE vehicle data APIs from AI coding agents, LLMs, and automated pipelines — including browser-based onboarding, machine-readable documentation, and content negotiation. CarsXE is built to be agent-friendly. Whether you are a coding agent onboarding a new project, an LLM reasoning about vehicle data, or an automation pipeline calling REST endpoints, this page covers the features we ship specifically for AI and agent use cases. Browser-based agent onboarding Getting a CarsXE API key from inside any AI agent — Claude Code, Claude Desktop, Cursor, Codex CLI, Gemini CLI, or any other coding assistant — takes just a few steps with no CLI install required. The agent directs you to a browser page, waits for you to authorize, then retrieves and stores your key automatically. The complete machine-readable skill document for agents is available at https://api.carsxe.com/agent-onboarding/SKILL.md. Agents that support skill discovery (such as Claude Code) will pick this up automatically. Step 1 — Give your agent the onboarding skill Pass the skill document URL to your agent so it knows exactly how to authenticate: "Use this skill to get a CarsXE API key: https://api.carsxe.com/agent-onboarding/SKILL.md" The agent fetches the skill, generates secure session parameters, then presents you with a clickable link to open in your browser. Step 2 — Authorize in the browser Click the link the agent provides. You will be taken to the CarsXE authorization page where you can sign in or create an account and approve access. No typing required — just click Authorize. Step 3 — Your agent retrieves the key Once you click Authorize, the agent polls in the background and retrieves your API key. It stores it automatically (typically as CARSXEAPIKEY in your environment or project .env file). Step 4 — Start making calls Your agent can immediately start making vehicle data calls on your behalf: "Decode VIN WBAFR7C57CC811956" "What is the market value of this vehicle with 50,000 miles?" "Check for any open recalls." Machine-readable documentation (Accept: text/markdown) CarsXE documentation pages support HTTP content negotiation. Send Accept: text/markdown on any documentation, support, or guide page to receive clean Markdown instead of HTML — fewer tokens, no layout markup, and higher signal for RAG pipelines and LLM context windows. How to use it Supported content types The site produces two content types: | Type | Description | | --------------- | ------------------------------------------------ | | text/html | Default browser response | | text/markdown | Clean Markdown — no layout, no navigation chrome | If the Accept header explicitly excludes both (for example Accept: application/pdf), the server returns 406 Not Acceptable with a plain-text body listing the available types. The Vary: Accept header All responses include Vary: Accept so HTTP caches store separate entries for the HTML and Markdown representations of the same URL. The Link: rel="alternate" header HTML responses on documentation, support, and guide pages include a Link header advertising the direct Markdown URL. Agents that inspect response headers can discover the Markdown endpoint without making a second request. Direct Markdown endpoint The /api/markdown/[[...slug]] route serves text/markdown unconditionally — no Accept header required. Use it when you want to hard-code the Markdown URL in a retrieval pipeline or a prompt template. Responses include Cache-Control: s-maxage=300, stale-while-revalidate=86400 and Vary: Accept. Site index for LLMs (llms.txt) The main CarsXE API site exposes a machine-readable index at https://api.carsxe.com/llms.txt. This document provides a plain-text overview of CarsXE for language models — product description, all API endpoints with pricing, subscription tiers, quick links, and recent blog posts. It is generated on each request with live pricing data so models always see current overage rates and tier names. Making API calls from an agent All endpoints accept key=YOURAPIKEY as a query parameter — the same environment variable the onboarding flow stores. POST endpoints also send the body as JSON with Content-Type: application/json. Vehicle Specifications (VIN Decode) Decode a VIN and retrieve full vehicle specifications: make, model, year, engine, trim, equipment, and more. See full reference. Market Value Estimate retail, trade-in, and auction values for a vehicle by VIN, with optional mileage, state, and condition adjustments. See full reference. Vehicle History Retrieve a comprehensive history report including title records, junk/salvage events, and insurance information for a VIN. See full reference. Vehicle Recalls Check for open safety recalls associated with a VIN. See full reference. Lien & Theft Check Check whether a vehicle has active liens or has been reported stolen. See full reference. Plate Decoder Look up a vehicle by license plate number. Supports 50+ countries. See full reference. International VIN Decoder Decode a non-US VIN from European, Asian, and other markets. See full reference. Vehicle Images Retrieve vehicle photos by make, model, and year. Supports filtering by color, angle, photo type, and size. See full reference. Year / Make / Model Look up vehicle data when you don't have a VIN — search by year, make, and model instead. See full reference. Plate Image Recognition Extract and decode a license plate number from an image URL. See full reference. VIN OCR Extract a VIN from a photo of a VIN plate or dashboard sticker. See full reference. OBD Codes Decoder Decode a diagnostic trouble code (DTC) from an OBD-II scanner — over 3,000 codes supported. See full reference. MCP server for AI tools For interactive AI editors and chat clients (Claude Desktop, Cursor, VS Code, Windsurf), the CarsXE MCP server is the recommended integration path — it exposes all endpoints as named tools and formats responses as Markdown automatically. See the MCP Quickstart Guide for installation instructions for each editor. What's next? - Agent onboarding skill document — machine-readable PKCE auth flow - llms.txt — full site index for LLMs - MCP Quickstart — MCP server for Claude, Cursor, VS Code, Windsurf - Claude Code Plugin — slash commands and auto-invoked skills - CLI Quickstart — terminal tool for agent-driven shell workflows - Authentication — API key management - Quickstart — first API call walkthrough --- ## Errors URL: /docs/guides/errors Every error the CarsXE API returns — what it means, why it happened, and how to fix it. Includes the error envelope, status codes, and retry guidance. This page is a complete reference for every error the CarsXE API can return. Each entry explains why the error happened and how to fix it, so you can resolve most issues without contacting support. You can tell whether a request succeeded from the HTTP status code. Every response body also includes a success boolean, so you can check either one. The error envelope All errors share the same JSON shape: Always false for errors. Successful responses return true. A human-readable description of what went wrong. Messages are stable strings — you can match on them — but prefer matching on the HTTP status code where possible. Present only on 429 quota errors. Contains current, limit, and remaining so you can see exactly where you stand. See Rate Limits & Quotas. A few legacy v1 routes return a 500 status for validation problems (for example, a missing make/model on the Images API). Always check the success field in addition to the status code when working with v1 endpoints. v2 endpoints use precise status codes throughout. Status codes | Status | Meaning | Safe to retry? | | --- | --- | --- | | 200 | Success. | — | | 202 | Accepted — an async job (e.g. Recalls Batch) was queued. Poll its status endpoint. | — | | 400 | Bad request — a parameter is missing or invalid. | No — fix the request first. | | 401 | Authentication failed — missing, invalid, or inactive API key. | No — fix your key or billing. | | 403 | Forbidden — your key is blocked or your plan doesn't include this API. | No | | 404 | Not found — no data exists for this VIN/plate, or an invalid state/country code. | No — same input returns the same result. | | 405 | Method not allowed — e.g. GET sent to a POST-only endpoint. | No — change the HTTP method. | | 429 | Usage quota exceeded. | Not as-is — quota errors persist until you upgrade, enable overage, or the period resets. See Rate Limits & Quotas. | | 500 | Internal server error. | Yes — once, with backoff. If persistent, contact support. | | 502 | Upstream data provider could not be reached. | Yes — with backoff. | | 503 | Upstream provider temporarily unavailable. | Yes — with backoff. | | 504 | Upstream request timed out. | Yes — with backoff. | Authentication errors | Message | Status | Why it happened | How to fix it | | --- | --- | --- | --- | | Missing API key | 401 | The request did not include the key parameter. | Pass your API key as the key query parameter on every request. See Authentication. | | User with this API key was not found or the API key is disabled | 401 | The key has a typo, was revoked, or was disabled. | Copy the key again from your dashboard. Check for whitespace or truncation. | | User with this API key is not active. To activate update your billing on https://api.carsxe.com/dashboard/billing | 401 | A payment failed or your billing is not in good standing, so API access was suspended. | Update your payment method on the billing page. Access resumes immediately after. | | This API key has been blocked, please contact support if you believe this is an error. | 403 | The key was flagged for abuse. | Contact support with your account email. | | This API is not available for your current subscription tier. Visit https://api.carsxe.com/pricing to review upgrade options. | 403 | Your plan does not include this endpoint. | Compare plans on the pricing page and upgrade, or remove the call. | Validation errors These are returned before any lookup happens, so they don't count against your quota. Fix the request and resend. | Message | Status | How to fix it | | --- | --- | --- | | Missing vin (vehicle identification number) | 400 | Pass the vin parameter. | | Wrong VIN length, must be 17 characters | 400 | VINs are exactly 17 characters. Strip whitespace; check for O/0 and I/1 transcription mistakes. | | Missing vehicle registration number or license plate number | 400 | Pass the plate parameter. | | Missing 2 letter state code | 400 | Pass state as a 2-letter code (e.g. CA). Required for US plate lookups. | | Invalid state or country code. | 404 | Use ISO-style 2-letter codes. See the supported-country list on the Plate Decoder page. | | Invalid condition. Available conditions: excellent, clean, average, rough | 400 | The condition parameter on Market Value v2 accepts only those four values. | | Invalid mileage. Must be a number | 400 | Pass mileage as digits only — no commas or units. | | Missing image data | 400 | VIN OCR and Plate Recognition need an image — pass a URL or base64 string. | | Invalid image data format. Must be a valid URL or base64 encoded string. | 400 | Check the URL is publicly reachable, or that the base64 payload is complete. | | Please supply a make and model. Visit http://api.carsxe.com/docs for more information | 500 | The Images API requires both make and model. (Legacy route — note the 500 status.) | The Recalls Batch endpoints have additional validation rules (VIN count, CSV size and hosting, webhook URLs) — those messages are self-describing and documented on the batch page. Data not found A 404 with one of these messages means the request was valid, but no data exists for that vehicle. Retrying the same input returns the same result. | Message | How to fix it | | --- | --- | | No data found for this VIN | Verify the VIN is correct. Coverage varies by market and model year. | | No data found for this VIN. Try a deep search by setting deepdata=1 in your request | Retry with deepdata=1 on the Specifications API for an extended-source lookup. | | Plate searches for this country have been disabled, or No data found for this plate | Check the plate and region. Some countries are unavailable; see the coverage list on the Plate Decoder page. | | No lien or theft data found for this VIN | No records exist — for many use cases this is the answer you want. | | No images found | Try a less specific query (drop trim or color). | | No plates detected in image | Use a sharper, better-lit image where the plate is clearly visible. | | No valid VIN candidates found in the image / No text detected in the image | Use a higher-resolution image of the VIN plate or windshield etching. | Not-found results for VIN lookups are cached for about one day. If you believe data should exist, wait before retrying rather than hammering the endpoint with the same VIN. Rate limit and quota errors A 429 means you've used up your plan's included volume for this API: See Rate Limits & Quotas for how limits work, the exact response shapes, and backoff strategies. Server and upstream errors CarsXE aggregates data from multiple providers. When a provider fails or times out, you'll see one of these: | Message | Status | What it means | What to do | | --- | --- | --- | --- | | Internal server error | 500 | An unhandled error on our side. | Retry once with backoff. If it persists, contact support with the endpoint, parameters, and timestamp. | | Unable to authenticate internal request (code CV-001). Please try again later | 500 | An internal provider credential issue — not your request. | Retry later. Quote the CV-001 code to support if it persists. | | Unable to authenticate internal request (code CV-002). Please try again later | 500 | Same as above, for the History API. | Retry later. Quote CV-002 to support. | | Could not fetch data | 502 | The upstream provider was unreachable or returned an error. | Retry with exponential backoff. | | Cannot access the internet at this time | 503 | The upstream provider is temporarily down. | Retry with backoff. | | Request timed out. Please try again. | 504 | The provider didn't respond in time. | Retry with backoff — these are usually transient. | Handling errors in code Check response.ok / the status code first, then branch on the category. Retry only 5xx — a 4xx (including quota 429s, which persist until you upgrade or enable overage) needs a fix, not a retry: CORS errors The CarsXE API is meant to be called from your server, never from the browser. This protects your API key from being stolen — any key shipped to a browser is public. If you call the API from frontend JavaScript, the browser will block the request with a CORS error. Route requests through your backend instead, and keep your key in an environment variable. Still stuck? If you've checked the tables above and the error doesn't make sense, contact support and include: - The endpoint and parameters you sent (redact your API key) - The full response body and HTTP status code - The timestamp (with timezone) of the failing request --- ## Organizations URL: /docs/guides/organizations Organizations let you share CarsXE API access with your team. Invite members, assign roles, and manage organization-wide API keys from a single workspace. Organizations are shared workspaces that let you collaborate with your team on CarsXE. Instead of every teammate managing their own account and API key, an organization gives you a single place to invite members, control what they can do with roles, and manage organization API keys that everyone can use. You manage organizations from your dashboard. No separate API is required. Billing is not organization-specific. Usage from organization API keys rolls up to the organization owner's personal subscription. There is no separate per-organization plan or invoice. Key concepts Roles & permissions Owner, admin, editor, and viewer roles control what each member can do. Team & invitations Invite teammates by email. Invitations expire after 7 days. Organization API keys Shared keys that authenticate API requests for the whole team. Billing Organization usage is billed to the owner's personal subscription. Roles and permissions Every member of an organization has one of four roles. The owner is the user who created the organization and cannot be removed. All other members are assigned one of the remaining roles. | Capability | Owner | Admin | Editor | Viewer | | --- | :---: | :---: | :---: | :---: | | View team & API keys | Yes | Yes | Yes | Yes | | Create API keys | Yes | Yes | Yes | No | | Enable/disable & rename API keys | Yes | Yes | Yes | No | | Delete API keys | Yes | Yes | No | No | | Invite members | Yes | Yes | No | No | | Update member roles & remove members | Yes | Yes | No | No | | Invite, promote, or manage admins | Yes | No | No | No | | Edit organization settings | Yes | No | No | No | | Delete the organization | Yes | No | No | No | Admins can manage editors and viewers, but only the owner can invite, promote, or manage other admins. The owner cannot be removed or have their role changed. Team and invitations Owners and admins can invite teammates to the organization by email, one at a time or in bulk. Each invitation is sent with the role you choose for the invitee. - Expiry — Invitations expire 7 days after they are sent. - Accepting — The invitee receives an email with a link to accept. They must sign in (or create an account) with the invited email address to join. - Pending & failed invites — The team view lists active members alongside any pending or failed invitations so you can resend them. - Removing members — Owners and admins can remove members at any time. Removing a member immediately revokes their access to the organization. Organization API keys Organization API keys work exactly like personal API keys when calling the CarsXE API — you pass them as the key parameter on any endpoint. The difference is that an organization key belongs to the workspace, so any current member can use it and key management is shared across the team. - Shared access — Any member can use an organization key to make API requests, subject to their role's permissions for managing keys. - Usage tracking — Each key tracks lifetime usage and monthly usage broken down by API type. - Status — A key is active only while the organization owner's subscription is active. If the owner's subscription becomes inactive, the organization's keys stop working until it is reactivated. Use an organization API key the same way you use any CarsXE key: See Authentication for more on how API keys authenticate your requests. Billing Organizations are a collaboration and access-management layer — they are not a billing entity. When a request is made with an organization API key, the usage resolves to the owner's account and counts against the owner's personal subscription. This means: - There is no separate organization plan, invoice, or payment method. - All organization API usage is consumed from the owner's subscription quota. - If the owner's subscription is inactive, every organization API key is inactive until the subscription is restored. Deleting an organization Only the owner can delete an organization. Deleting an organization removes the team's access to its shared API keys. Be sure your team has migrated to other keys before deleting. Get started Ready to set up your team? Head to your dashboard to create an organization, invite members, and generate your first organization API key. --- ## Rate Limits & Quotas URL: /docs/guides/rate-limits How CarsXE usage limits work — included monthly volume, the 429 response shape, overage billing, usage alerts, and how to handle limits in code. CarsXE limits are volume-based quotas tied to your subscription, not per-second throttles. Each API has an included monthly volume for your tier; when you reach it, what happens next depends on your overage settings. This page explains how the quotas work, exactly what a 429 looks like, and how to handle limits gracefully in code. There are no per-second request throttles on standard plans, but keep burst concurrency reasonable — extremely aggressive parallel traffic can still be rejected upstream before it reaches your quota. How quotas work - Per-API quotas. Each API (Specs, Market Value, History, …) has its own included monthly volume, determined by your subscription tier. A few related APIs share a combined quota. - Monthly reset. Usage counters reset at the start of each billing period. Trial allowances are one-time — they do not reset monthly. - Units, not requests. Most requests consume 1 unit. Bulk endpoints (for example Recalls Batch) consume one unit per VIN, so a 500-VIN batch uses 500 units in a single request. - Failed validation is free. Requests rejected with a 400 validation error (missing VIN, bad parameter, etc.) are blocked before any lookup and don't count against your quota. - Plan-gated APIs. Some APIs aren't included in lower tiers at all. Calling one returns a 403 — see Errors — not a 429. You can see your current usage per API at any time on the developer dashboard. What happens when you hit the limit There are two possible behaviors, controlled by your overage billing preference in the dashboard: | Overage billing | Behavior past the included quota | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Enabled (default on plans with overage pricing) | Requests keep succeeding. Each unit past your included volume is billed at your tier's per-call overage rate. You will never see a quota 429. | | Disabled (opt-out) | Requests are rejected with a 429 until the period resets or you re-enable overage. | Enterprise plans use custom pricing and monthly invoicing — included volume and overage terms are set in your contract. The 429 response Quota errors use the standard error envelope plus a usage object: Units consumed so far this billing period (or in total, for one-time trial allowances). Your included volume for this API on your current tier. Units left before the limit. 0 when the request was rejected. The message tells you which API hit its limit, the billing period (month/year), your tier, and the exact numbers. Variants you may see: - This request requires N units. — appended when a bulk request would exceed the limit even though current < limit. Reduce the batch size to fit within remaining, or split it across billing periods. - Please upgrade your tier to continue using the API. — appended for one-time (trial) allowances that never reset. Waiting won't help; upgrade to continue. - Enable overage billing in your dashboard billing preferences to continue with overage charges: … — appended when you've opted out of overage but your plan supports it. Re-enable overage on the developer dashboard and the same request will succeed immediately. Usage alerts You don't have to discover a quota 429 in production. CarsXE emails the account owner when an API reaches 80%, 90%, and 100% of its included volume, so you can upgrade or enable overage before requests start failing. Handling 429s in code A quota 429 is not transient — unlike a 5xx, retrying with backoff won't make it succeed. The right response depends on usage: Two practical patterns: - Track usage.remaining proactively. It's returned on quota errors, and your live numbers are always on the dashboard. Alerting at your own threshold (say 75%) gives you more lead time than the built-in emails. - Size batches to fit. Before a bulk call, make sure the VIN count is at or below your remaining units — a rejected batch consumes nothing, but it also accomplishes nothing. For generic retry/backoff handling of 5xx errors, see the full code samples on the Errors page. Raising your limits - Upgrade your tier for more included volume on every API — compare plans on the pricing page. - Enable overage billing to never be blocked: usage past the included volume is billed per call at your tier's rate. - Go enterprise for high or spiky volume: custom quotas, custom pricing, and consolidated monthly invoicing. Contact us to talk through your numbers. --- ## Supported Countries URL: /docs/guides/supported-countries Reference for the country parameter accepted by CarsXE API endpoints — valid values, regional requirements, and per-endpoint coverage. Several CarsXE endpoints accept an optional country parameter as an ISO 3166-1 alpha-2 code (e.g. country=DE). It defaults to US when omitted. This page is the authoritative reference for valid values and per-endpoint behavior. Endpoint coverage | Endpoint | Accepts country | Coverage | |---|---|---| | GET /v2/platedecoder | Yes | 57 countries — see table below | | GET /v2/marketvalue | Yes | Primarily US | Regional requirements Some endpoints require additional location context depending on the country: - State or province is required for US, Australian, Canadian, and Pakistani lookups — use the standard two-letter code (e.g. CA, NSW, ON). - Pakistan additionally supports a district parameter for more precise lookups. Coverage and field availability vary by country. Some regions return a full data set; others return only identity fields like make, model, and year. All supported countries The table below reflects the full set of countries supported by /v2/platedecoder. Other endpoints may support a subset. | Code | Country | Code | Country | |---|---|---|---| | AE | United Arab Emirates | AL | Albania | | AR | Argentina | AU | Australia | | BE | Belgium | BO | Bolivia | | BR | Brazil | CA | Canada | | CH | Switzerland | CL | Chile | | CN | China | CO | Colombia | | CR | Costa Rica | CY | Cyprus | | CZ | Czech Republic | DE | Germany | | DK | Denmark | EC | Ecuador | | EE | Estonia | ES | Spain | | FI | Finland | GB | United Kingdom | | GR | Greece | HR | Croatia | | HU | Hungary | IE | Ireland | | IL | Israel | IM | Isle of Man | | IN | India | IS | Iceland | | IT | Italy | KZ | Kazakhstan | | LK | Sri Lanka | LT | Lithuania | | LV | Latvia | MT | Malta | | MX | Mexico | MY | Malaysia | | NG | Nigeria | NL | Netherlands | | NO | Norway | NZ | New Zealand | | OM | Oman | PE | Peru | | PK | Pakistan | PL | Poland | | PT | Portugal | RO | Romania | | RU | Russia | SE | Sweden | | SG | Singapore | SI | Slovenia | | SK | Slovakia | TN | Tunisia | | TW | Taiwan | UA | Ukraine | | US | United States | ZA | South Africa | Spain — guaranteed VIN Spain (ES) has a special requirevin=1 parameter available on /v2/platedecoder. By default, Spanish plate lookups use a standard provider that does not guarantee a VIN. Pass requirevin=1 to route through a higher-cost provider that always includes a VIN in the response. This costs 2× a standard lookup and only applies to country=ES on the plate decoder endpoint. See the Plate Decoder docs for full parameter details. --- ## Integrations URL: /docs/integrations Official CarsXE integrations for AI agents, data platforms, and automation tools. Integrate CarsXE vehicle data into AI tools, data warehouses, and no-code automation platforms. Use these guides when you need CarsXE outside a direct SDK integration. AI integrations ### MCP Server Connect CarsXE to Claude Desktop, Cursor, VS Code, Windsurf, and other MCP-compatible clients. ### Claude Plugin Use CarsXE commands and auto-invoked skills directly inside Claude Code. ### Gemini Extension Add CarsXE vehicle data commands and skills to Gemini CLI. ### OpenClaw Skill Give OpenClaw agents access to VIN decoding, plate lookups, history, recalls, market values, and more. Data tools ### Snowflake Decode VINs and enrich vehicle datasets from the CarsXE Snowflake Native App. Automation ### n8n Use the official CarsXE community node in n8n workflows. ### Zapier Connect CarsXE to thousands of Zapier apps for no-code vehicle data automation. ### Make Build visual Make scenarios that call CarsXE APIs alongside your existing tools. --- ## Claude Plugin URL: /docs/integrations/claude-quickstart Access the full suite of CarsXE vehicle data APIs directly from Claude Code — decode VINs, look up license plates, get market values, check history, recalls, liens, OBD codes, and more. What is the CarsXE Plugin for Claude Code? The CarsXE Plugin for Claude Code provides direct access to our comprehensive automotive APIs through simple commands and auto-invoked skills. Decode VINs, look up license plates, get market values, check vehicle history, recalls, liens, OBD codes, and more — all within your Claude Code environment. GitHub Repository: carsxe-claude-plugin Plugin Marketplaces You can also find and install the CarsXE plugin from these Claude plugin directories: - Claude Plugin Hub - Build With Claude Installation Step 1: Add the CarsXE Marketplace Step 2: Install the Plugin Setup 1. Get Your CarsXE API Key 1. Visit the CarsXE API dashboard 2. Navigate to your API keys section 3. Copy your API key 2. Authenticate with Your API Key Use the auth command to validate credentials and establish session access: /carsxe:auth yourapikey_here Available Commands | Command | Description | | ------------------------------------------ | ------------------------------------- | | /carsxe:auth | Validate and configure API credentials | | /carsxe:specs | Decode a VIN — full vehicle specs | | /carsxe:plate [STATE] | Look up vehicle from license plate | | /carsxe:value | Get current market value | | /carsxe:history | Full vehicle history report | | /carsxe:images [YEAR] | Fetch vehicle photos | | /carsxe:recalls | Check for open safety recalls | | /carsxe:intvin | Decode international (non-US) VINs | | /carsxe:ocr | Extract VIN from a photo | | /carsxe:lien | Check for liens and theft records | | /carsxe:plateocr | Extract license plate from a photo | | /carsxe:ymm [TRIM] | Look up vehicle by Year/Make/Model | | /carsxe:obd | Decode an OBD diagnostic trouble code | Usage Examples Decode a VIN /carsxe:specs WBAFR7C57CC811956 Look up a California Plate /carsxe:plate 7XER187 US CA Check Market Value /carsxe:value WBAFR7C57CC811956 Get Vehicle History /carsxe:history WBAFR7C57CC811956 Find Vehicle Images /carsxe:images BMW X5 2019 Check Recalls /carsxe:recalls WBAFR7C57CC811956 Decode an International VIN /carsxe:intvin WF0MXXGBWM8R43240 Extract VIN from a Photo /carsxe:ocr https://example.com/vin-photo.jpg Check Liens and Theft /carsxe:lien WBAFR7C57CC811956 Extract Plate from a Photo /carsxe:plateocr https://example.com/plate-photo.jpg Look up by Year/Make/Model /carsxe:ymm 2020 Toyota Camry LE Decode an OBD Code /carsxe:obd P0300 Skills (Auto-invoked) Skills are automatically triggered by Claude based on the conversation context. No need to type a command — just describe what you need naturally. | Natural Language Query | Triggered Skill | | ---------------------------------------------- | ----------------- | | "What are the specs of VIN WBAFR7C57CC811956?" | vehicle-specs | | "Does this car have any recalls?" | vehicle-recalls | | "What does the check engine code P0300 mean?" | obd-decoder | | "What's the value of this vehicle?" | market-value | | "Show me images of a 2020 Tesla Model 3" | vehicle-images | | "Get the history report for this VIN" | vehicle-history | Troubleshooting Common Issues Authentication Error - Verify your API key is correct - Ensure the CARSXEAPIKEY environment variable is set - Check that your API key has the necessary permissions Plugin Not Found - Verify you've added the marketplace correctly - Try reinstalling the plugin - Restart Claude Code Command Not Working - Check the command syntax matches the examples above - Ensure all required parameters are provided - Verify your API account has sufficient credits Ready to supercharge your vehicle data workflows with CarsXE and Claude Code! --- ## Gemini Extension URL: /docs/integrations/gemini-quickstart Access the full suite of CarsXE vehicle data APIs directly from Gemini CLI — decode VINs, look up license plates, get market values, check history, recalls, liens, OBD codes, and more. What is the CarsXE Extension for Gemini CLI? Access the full suite of CarsXE vehicle data APIs directly from Gemini CLI. Decode VINs, look up license plates, get market values, vehicle history, recalls, lien and theft records, OBD codes, and more. GitHub Repository: carsxe-gemini-extension Features | Command | Description | | ------------------------------------------ | --------------------------------------------- | | /carsxe:auth | Validate and set your CarsXE API key | | /carsxe:specs | Decode a VIN with full vehicle specifications | | /carsxe:plate [STATE] | Look up a vehicle by license plate | | /carsxe:value | Get current market value | | /carsxe:history | Full vehicle history report | | /carsxe:images [YEAR] | Retrieve vehicle photos | | /carsxe:recalls | Check for open safety recalls | | /carsxe:intvin | Decode an international (non-US) VIN | | /carsxe:ocr | Extract a VIN from a photo (OCR) | | /carsxe:lien | Check for liens and theft records | | /carsxe:plateocr | Extract a plate number from a photo | | /carsxe:ymm [TRIM] | Look up by Year/Make/Model | | /carsxe:obd | Decode an OBD-II trouble code | All commands also have corresponding skills that Gemini auto-invokes when it detects relevant context in your conversation. Prerequisites Before installing the extension, make sure you have the Gemini CLI installed and your GEMINIAPIKEY environment variable set. You can get a Gemini API key from Google AI Studio. macOS / Linux — add to your shell profile for persistence: If you use Zsh (default on macOS), replace ~/.bashrc with ~/.zshrc. Windows — PowerShell (current session): Windows — PowerShell (persist across sessions): Windows — Command Prompt: After setx, restart your terminal for the variable to take effect. Installation Install the extension from the GitHub repository: During installation, Gemini CLI prompts you for your CarsXE API key. If you do not have a key yet, sign up and get one from the CarsXE developer dashboard. If you skipped that prompt, or you want to change your API key after installing, run: This stores your API key securely in the system keychain. Usage Examples Decode a VIN Look up a license plate Get market value Vehicle history report Vehicle images Check recalls International VIN VIN OCR from image Lien and theft check Plate recognition from image Year/Make/Model lookup OBD code decode Skills (Auto-invoked) Gemini will automatically use the CarsXE tools when it detects relevant queries. For example: - "What can you tell me about VIN WBAFR7C57CC811956?" — triggers the vehicle-specs skill - "Does this car have any recalls? VIN: WBAFR7C57CC811956" — triggers the vehicle-recalls skill - "My check engine light is on with code P0300" — triggers the obd-decoder skill - "How much is a 2012 BMW X5 worth? VIN WBAFR7C57CC811956" — triggers the market-value skill API Documentation Full API documentation is available at api.carsxe.com/docs. --- ## Make URL: /docs/integrations/make-quickstart Build visual CarsXE automation scenarios in Make for VIN decoding, plate lookups, market values, history checks, recalls, and other vehicle data workflows. What is the CarsXE integration for Make? The CarsXE Make integration lets you call CarsXE vehicle data APIs from visual automation scenarios. Use it to enrich records, route vehicle data, update inventory systems, and send alerts without writing custom integration code. Make App Library: CarsXE API on Make Prerequisites Before you begin, make sure you have: 1. A Make account 2. A CarsXE API account — sign in or create an account 3. A CarsXE API key from the developer dashboard Setup Step 1: Add CarsXE to a scenario Open CarsXE API on Make, or create a new scenario in Make and search for CarsXE API when adding a module. Step 2: Create the CarsXE connection When Make prompts for credentials, paste your CarsXE API key. Save the connection so it can be reused across scenarios. Step 3: Configure a module Choose the CarsXE operation you need, map fields from earlier modules, then run the scenario once to verify the response shape. Example Scenarios Decode VINs from a spreadsheet Watch for new inventory rows, decode VINs, and write vehicle specifications back to your data store. Route plate lookups Accept plate lookup requests through a webhook, resolve vehicle data, then route results based on country, make, or model. Add market values to inventory Fetch current market value estimates and keep internal inventory records up to date. Send recall alerts Check vehicles on a schedule and notify your team when recalls need review. Common Fields | Field | Used for | | --- | --- | | VIN | VIN decoding, market value, history, recalls, lien and theft checks | | Plate | License plate lookups | | Country | Plate lookup country, such as US | | State | Optional region for plate lookups, such as CA | | Make, Model, Year | Vehicle image and Year/Make/Model workflows | Troubleshooting Connection cannot be created - Confirm that your CarsXE API key is valid. - Make sure your CarsXE account has an active subscription or available credits. - Create a new CarsXE key and update the Make connection if the old key was rotated. Scenario run fails - Verify that required module fields are mapped. - Confirm VINs are 17 characters. - For plate lookups, include country and state when the source market requires it. Mapped fields are empty - Run the CarsXE module once with sample data so Make can inspect the response. - Confirm the selected operation returns the vehicle data you expect. Support - Make listing: CarsXE API on Make - CarsXE documentation: Full API documentation - Support: Contact Support --- ## MCP Server URL: /docs/integrations/mcp CarsXE MCP server for AI editors — Claude Desktop, Cursor, VS Code, Windsurf. The CarsXE MCP server exposes vehicle data directly to AI editors and agents. Once configured, Claude Desktop, Cursor, VS Code, and Windsurf can look up VINs, decode plates, pull recalls, and more — all from within your AI workflow. Available tools | Tool | Description | |---|---| | get-vehicle-specs | Full vehicle specifications from a VIN | | decode-vehicle-plate | License plate → VIN lookup (50+ countries) | | international-vin-decoder | Decode non-US international VINs | | get-market-value | Retail, trade-in, and auction estimates | | get-vehicle-history | Title events, salvage, and insurance records | | get-vehicle-images | Vehicle photos by make, model, and year | | get-vehicle-recalls | Open safety recalls by VIN | | recognize-plate-image | Extract plate info from an image URL | | vin-ocr | Extract VIN text from an image via OCR | | get-year-make-model | Look up vehicles by year, make, and model | | decode-obd-code | Decode OBD-II diagnostic trouble codes | Setup Add the CarsXE server to your editor's MCP configuration. Replace yourkeyhere with your API key from the developer dashboard. Config file locations | Editor | Config file | |---|---| | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claudedesktopconfig.json | | Claude Desktop (Windows) | %APPDATA%\Claude\claudedesktopconfig.json | | Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) | | VS Code | .vscode/mcp.json (project) or User Settings JSON | | Windsurf | ~/.codeium/windsurf/mcp_config.json | Using the tools After configuration, restart your editor. The CarsXE tools will appear in your AI assistant's tool list. You can invoke them naturally: "What are the specs for VIN WBAFR7C57CC811956?" "Are there any open recalls on this car?" "What's the market value of a 2019 BMW 5 Series with 45,000 miles in California?" The server formats all responses as readable Markdown so results are easy to scan in chat. Best practices Use npx -y to always run the latest version. The -y flag skips the install confirmation prompt and ensures you're on the current release. Never commit your API key. Store it only in the editor config file (which lives outside your repo) or in a secrets manager. Rotate it from the developer dashboard if it's ever exposed. --- ## n8n URL: /docs/integrations/n8n-quickstart Connect CarsXE vehicle data APIs to your n8n workflows — decode VINs, look up license plates, check vehicle history, market values, recalls, and more using the official CarsXE node. What is the CarsXE Node for n8n? The CarsXE node for n8n is an official community node that brings comprehensive vehicle data to your automation workflows. Decode VINs, look up license plates, fetch market values, run history reports, check recalls, and more — all without writing a single line of code. n8n Integration Page: n8n.io/integrations/carsxe npm Package: n8n-nodes-carsxe Prerequisites Before you begin, ensure you have: 1. A running n8n instance (cloud or self-hosted) 2. A CarsXE API account — Sign in or create an account here 3. Your CarsXE API key Installation Via Community Nodes (Recommended) 1. In your n8n instance, go to Settings → Community Nodes 2. Click Install a community node 3. Enter n8n-nodes-carsxe 4. Click Install Via npm (Self-hosted) Via Docker Setup Step 1: Get Your API Key 1. Visit the CarsXE API dashboard 2. Navigate to your API keys section 3. Copy your API key Step 2: Add CarsXE Credentials in n8n 1. In n8n, go to Credentials → New 2. Search for CarsXE API 3. Paste your API key and click Save Available Operations VIN Operations | Operation | Description | |-----------|-------------| | Decode VIN | Full vehicle specifications from a 17-character VIN | | Decode International VIN | Worldwide VIN support for non-US vehicles | | Get History Report | Ownership records and accident history | | Get Market Value | Current market valuation | | Get Safety Recalls | Manufacturer recall information | License Plate Operations | Operation | Description | |-----------|-------------| | Decode License Plate | Vehicle information from a plate number (US, CA, AU, UK, and more) | | Recognize Plate From Image | OCR extraction of a plate number from a photo URL | Vehicle Data Operations | Operation | Description | |-----------|-------------| | Get Images | Professional vehicle photos by make, model, and year | | Query by Year/Make/Model | Search vehicle data without a VIN | Diagnostic Operations | Operation | Description | |-----------|-------------| | Decode OBD Code | Interpret check engine and diagnostic trouble codes | | Extract VIN From Image | OCR extraction of a VIN from a photo URL | Example Workflows VIN Decoder API Receive a VIN via webhook and instantly return full vehicle specifications to the caller. License Plate Scanner Accept a plate number and country, look up the vehicle, and store the result in your database. Daily Recall Checker Run a scheduled check against a list of VINs and notify your team of any newly issued recalls. Market Value Monitor Periodically pull updated market valuations for your inventory and sync them to a spreadsheet or CRM. Quick Example: Decode a VIN Configure the CarsXE node with: | Field | Value | |-------|-------| | Resource | VIN | | Operation | Decode VIN | | VIN | WBAFR7C57CC811956 | Response: Quick Example: License Plate Lookup Configure the CarsXE node with: | Field | Value | |-------|-------| | Resource | License Plate | | Operation | Decode License Plate | | Plate | 7XER187 | | Country | US | | State (Additional Options) | CA | Response: Troubleshooting Common Issues "Request failed with status code 401" - Check your API key in Credentials - Ensure your account has sufficient credits - Generate a new key from the CarsXE Dashboard "Invalid VIN format" - VINs must be exactly 17 characters - Example: WBAFR7C57CC811956 Node not appearing after installation - Refresh your browser - Clear the n8n cache: rm -rf ~/.n8n/cache - Restart your n8n instance Ready to automate your vehicle data workflows with CarsXE and n8n! --- ## OpenClaw Skill URL: /docs/integrations/openclaw-quickstart Access the full suite of CarsXE vehicle data APIs directly from OpenClaw — decode VINs, look up license plates, get market values, check history, recalls, liens, OBD codes, and more. What is the CarsXE Skill for OpenClaw? OpenClaw is an AI agent platform that extends a conversational AI into a capable assistant through a skill system. The CarsXE skill gives your OpenClaw agent comprehensive automotive data capabilities — decode VINs, look up license plates, get market values, check vehicle history, recalls, lien and theft records, OBD codes, and more, all without leaving your agent environment. Skills are installed from Clawhub, OpenClaw's official skill marketplace. The CarsXE skill is listed at CarsXE. Installation Install the CarsXE skill from Clawhub with a single command: Setup Set Your CarsXE API Key After installation, configure the skill with your CarsXE API key: Then restart the OpenClaw gateway for the change to take effect. Don't have an API key yet? Get one from the CarsXE developer dashboard. Verify the Key is Set The skill reads your key from the CARSXE_KEY environment variable. If it is missing or empty, OpenClaw will display an error. Re-run the config command above with your actual key and restart the gateway. Usage Examples The skill is auto-invoked based on context — just describe what you need naturally. OpenClaw selects the right endpoint and chains requests when required. Decode a VIN What are the specs for VIN WBAFR7C57CC811956? Decode a License Plate Decode California plate 7XER187. Get Market Value What's my car worth? VIN WBAFR7C57CC811956, 45k miles, clean condition, California. Check Safety Recalls Does VIN 1C4JJXR64PW696340 have any open safety recalls? Lien and Theft Check Check liens and theft records for VIN WBAFR7C57CC811956. Vehicle History Report Show me the full history report for VIN WBAFR7C57CC811956. Decode an International VIN Decode this international VIN: WF0MXXGBWM8R43240. Year/Make/Model Lookup Look up a 2020 Toyota Camry LE. OBD Code Diagnosis My check engine light shows P0300 — what does that mean? VIN from a Photo Extract the VIN from this photo: https://example.com/vin.jpg Plate from a Photo Extract the plate number from this photo: https://example.com/plate.jpg Vehicle Images Get vehicle images for a 2019 BMW X5. Chained Requests The skill automatically chains multiple API calls when a query requires it. For example: "Is this plate stolen and does it have open recalls?" 1. GET /v2/platedecoder — resolve the plate to a VIN 2. GET /v1/lien-theft + GET /v1/recalls — run both checks in parallel against the VIN OpenClaw handles the chaining transparently and presents a combined result. Error Handling | HTTP Status | Meaning | What Happens | | ----------- | ------- | ------------ | | 401 / invalid key | Bad or missing API key | OpenClaw prompts you to set the key via openclaw config set | | 404 / no results | VIN or plate not found | You are informed and asked to double-check the input | | 429 | Rate limit exceeded | The skill waits and retries automatically | | 5xx | Server error | Retried once; error is reported if it persists | The skill also checks the error field in JSON responses — CarsXE can return HTTP 200 with an error body, and these are caught and surfaced to you. Managing the Skill Update the Skill Disable Without Removing Troubleshooting Authentication error / invalid key - Run openclaw config set skills.entries.carsxe.env.CARSXEKEY "cxeliveYOURKEY" with your actual key - Restart the OpenClaw gateway after updating the key - Ensure your CarsXE account has an active subscription Skill not found after install - Restart your OpenClaw session - Verify installation with openclaw skills list - Check that carsxe is listed as enabled: true in your openclaw.json Tool not being auto-invoked - Ensure the skill is enabled in openclaw.json - Restart the gateway to reload the skill registry - Describe your request more specifically if the skill is not triggering Getting Help - Clawhub listing: carsxe - CarsXE documentation: Full API Documentation - Support: Contact Support Ready to power your OpenClaw agent with comprehensive vehicle data from CarsXE! --- ## Snowflake URL: /docs/integrations/snowflake-quickstart Access comprehensive vehicle data directly in Snowflake through CarsXE's powerful API. This Native App provides an intuitive Streamlit interface and SQL callable procedures for seamless integration into your data workflows. CarsXE Vehicle Data for Snowflake Get started with the CarsXE Snowflake Native App for comprehensive vehicle data access directly in your Snowflake environment. Features - Vehicle Data Endpoints including VIN decoding, plate lookup, market value, history, images, recalls, Lien And Theft checks, and more - Streamlit UI with guided setup and interactive endpoint testing - SQL Interface for direct procedure calls in your queries and workflows - Secure API Key Storage encrypted within your Snowflake account - Auto-Navigation through setup steps for quick onboarding Prerequisites - A Snowflake account with Native App installation permissions - A CarsXE account with an active API key (Sign up here) - The app only requires outbound access to api.carsxe.com and does not access any other external domains. Installation 1. Install from Snowflake Marketplace - Search for "CarsXE" - Select the "Vehicle Data from CarsXE" - Click "Get" and follow the installation prompts 2. Open the App - Navigate to the installed app in your Snowflake account - The setup wizard will launch automatically 3. Complete Setup (3 Simple Steps) The app guides you through each step: Step 1: Connect External Access - Click "Connect CarsXE EAI ↗" - Select or create an External Access Integration for api.carsxe.com Step 2: Add Your API Key - Enter your CarsXE API key - Click "Validate API key" to verify and save - Note: The API key is now stored securely using a bind variable in the CORE.CONFIG table to prevent SQL identifier issues. Step 3: Start Using the APIs - You're ready! Select an endpoint and make your first call Using the Streamlit UI 1. Choose an Endpoint from the dropdown menu (e.g., "Specs (VIN specs)") 2. Enter Required Fields (marked clearly in the form) 3. Add Optional Parameters if needed (expand "Optional parameters" section) 4. Click "Call endpoint" to get results Using SQL Directly You can call the app fully through SQL, without using the UI, via: Parameters: - path – API endpoint path (e.g., "/specs", /v2/platedecoder, /v2/marketvalue). For a complete list of available endpoints and their versions, see the CarsXE API Documentation - method – "GET" or "POST" (most endpoints use GET; some endpoints like plate recognition and VIN OCR use POST. Check the API Documentation for endpoint-specific method requirements) - params – JSON string with endpoint-specific parameters (do not include key; the app injects it automatically) SQL Examples Important: Before using these SQL examples, you must complete the setup steps in the Streamlit UI app, including configuring the External Access Integration (EAI) and adding your API key. See the Installation section above for details. Validating API Key Saving API Key Note: The API key storage now uses a bind variable internally to avoid SQL compilation errors with identifiers. Specs by VIN Plate Decoder Market Value Images Plate Image Recognition (image URL) VIN OCR (image URL) Lien And Theft Check Internally, each call automatically adds key= in the request to CarsXE. Security & Governance - The API key is stored securely in the CORE.CONFIG table using a bind variable to prevent SQL injection and identifier issues. - All external HTTP calls run through a Snowflake External Access Integration approved for the app, which follows Snowflake governance policies. - The app does not store, cache, or log CarsXE API responses outside the execution context of the request; it simply returns them to the caller (UI or SQL). Limitations - No built-in caching: each call goes directly to CarsXE, which means latency and rate limits depend on your CarsXE plan and network conditions. - The app does not modify or normalize CarsXE responses; it returns them as received (wrapped in JSON where necessary). Support - For API behavior, data quality, pricing, or rate limit issues, contact CarsXE support via their official channels. - For issues specific to this Snowflake Native App (installation errors, procedure failures, UI errors), use the contact information provided on the Snowflake Marketplace listing. --- ## Zapier URL: /docs/integrations/zapier-quickstart Connect CarsXE vehicle data APIs to Zapier workflows and automate VIN decoding, plate lookups, market values, history checks, recalls, and more. What is the CarsXE integration for Zapier? The CarsXE Zapier integration lets you add vehicle data to no-code workflows. Use it to enrich leads, inventory rows, forms, support tickets, and internal alerts with CarsXE data such as VIN specifications, license plate lookups, market values, history, recalls, and images. Zapier App Directory: CarsXE on Zapier Prerequisites Before you begin, make sure you have: 1. A Zapier account 2. A CarsXE API account — sign in or create an account 3. A CarsXE API key from the developer dashboard Setup Step 1: Open CarsXE in Zapier Go to CarsXE on Zapier, then click Connect CarsXE or add CarsXE as an action in a Zap. Step 2: Connect your CarsXE account When Zapier asks for credentials, paste your CarsXE API key. Zapier stores the connection and reuses it for future CarsXE actions. Step 3: Build a Zap Choose a trigger from another app, add a CarsXE action, map the required fields, and test the action before publishing. Example Zaps Decode VINs from form submissions Collect a VIN from a form, decode vehicle specifications, and write the enriched result to your CRM or spreadsheet. Enrich license plate leads Resolve a plate number into vehicle data, then notify your sales or operations team. Monitor vehicle recalls Run scheduled recall checks and send alerts when a vehicle needs attention. Sync market values Pull current market valuation data for vehicles in inventory and keep downstream tools updated. Common Fields | Field | Used for | | --- | --- | | VIN | VIN decoding, market value, history, recalls, lien and theft checks | | Plate | License plate lookups | | Country | Plate lookup country, such as US | | State | Optional region for plate lookups, such as CA | | Make, Model, Year | Vehicle image and Year/Make/Model workflows | Troubleshooting Authentication failed - Confirm that the API key was copied from the CarsXE developer dashboard. - Make sure your CarsXE account is active and has available credits. - Reconnect the CarsXE account in Zapier if the key was rotated. Zap test returns no vehicle - Check that VINs are 17 characters. - For plate lookups, include the correct country and state when required. - Test the same input in the CarsXE docs or dashboard to confirm the source data. A field is missing in a later Zap step - Re-run the CarsXE action test so Zapier refreshes the sample response. - Confirm the selected CarsXE action returns the field you want to map. Support - Zapier listing: CarsXE on Zapier - CarsXE documentation: Full API documentation - Support: Contact Support --- ## Products URL: /docs/products Guides for every CarsXE API product — use cases, response walkthroughs, and common patterns. Deep dives into each CarsXE API product. Each guide explains when to use the endpoint, how to interpret the response, and common integration patterns. --- ## International VIN Decoding URL: /docs/products/international-vin-decoder Decode non-US VINs from international markets into structured vehicle identity, manufacturer, and technical attributes. Decode an international VIN when a vehicle is outside the standard US specification data set. The endpoint returns the decoded attributes that are available for the VIN, including make, model, year, body, manufacturer, plant country, drivetrain-related details, dimensions, and capacity fields when the source provides them. Use this endpoint directly for non-US VIN workflows, or use the Specifications endpoint and leave disableIntVINDecoding unset so it can fall back to International VIN Decoding when a standard VIN decode has no result. Parameters | Parameter | Required | Description | |---|---|---| | vin | Yes | The vehicle identification number to decode | | key | Yes | Your CarsXE API key | Example Response For the full interactive reference, try it live in the API Reference. All response fields other than success and input are optional. International VIN coverage varies by manufacturer, market, and model year, so missing fields mean the decoding source did not provide that attribute for the VIN. Top-level fields true when the VIN was decoded successfully. Echoes the VIN submitted in the request. Decoded vehicle fields. Common fields include vin, make, model, year, producttype, body, series, fueltype, manufacturer, plant_country, dimensions, weights, brakes, suspension, and VIN metadata. ISO 8601 response time. Common attribute groups Identity — Core decoded vehicle identity The decoded vehicle identification number. Example: "WF0MXXGBWM8R43240". Manufacturer or brand. Example: "Ford". Model family. Example: "Galaxy". Model year when available. Example: "2008". Vehicle category such as "Car" or "Truck". Body classification such as "Wagon" or "Pickup". Manufacturer and plant — Builder and production details Manufacturer name and address when supplied by the decoding source. Manufacturer address when available separately. Country where the vehicle was built. Example: "Germany". Engine manufacturer when available. Technical data — Engine, dimensions, capacity, and VIN metadata Fuel type such as "Diesel" or "Gasoline". Transmission gear count when decoded. Wheelbase in millimeters when available. Vehicle height in millimeters when available. Vehicle length in millimeters when available. Vehicle width in millimeters when available. VIN check digit. VIN sequential production number segment. --- ## Lien & Theft URL: /docs/products/lien-theft Check whether a vehicle has active liens or has been reported stolen. Check a US VIN for lien and theft-related records. The /v1/lien-theft endpoint returns decoded vehicle context plus any reportable lien or theft events CarsXE finds for the VIN. Results depend on available reporting sources and jurisdictions. Treat missing fields as unavailable data from the source, not as proof that the vehicle is clear. Parameters | Parameter | Required | Description | |---|---|---| | vin | Yes | The 17-character vehicle identification number | | key | Yes | Your CarsXE API key | Example Response Top-level shape Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference. All response fields are optional except fields included in a successful response. Empty or missing events means CarsXE did not receive an event group for that VIN in that response. true on a successful 200 response. Echo of request inputs, including the VIN that was checked. ISO 8601 response timestamp. Decoded vehicle model year returned with the record. Decoded vehicle manufacturer. Decoded vehicle model. Vehicle category returned by the source. Example: "CAR". Lien or theft-related records found for the VIN. Optional decoded trim or source-specific vehicle details when returned. events Each item in events is a reportable lien or theft-related record. Event payloads can include additional source-specific fields. Human-readable event label. Example: "Recovered Theft". State or jurisdiction abbreviation when available. Example: "OH". Human-readable details from the source record. How to interpret results Use this endpoint as a screening signal, not as a complete legal determination of title status. - A 200 with events means CarsXE found reportable lien or theft-related records for the VIN. - A 404 with "No lien or theft data found for this VIN" means this endpoint did not find lien or theft data for that VIN. - Missing fields mean the source did not provide that value in the returned record. Errors See the Errors guide for the full list. The most common cases specific to this endpoint: - 400 — "Missing vin (vehicle identification number)" or "Wrong VIN length, must be 17 characters" — fix the input, don't retry. - 401 — missing or invalid API key. - 404 — "No lien or theft data found for this VIN" — no lien or theft data was found by this endpoint for the VIN. - 429 — usage limit exceeded. --- ## Market Value URL: /docs/products/market-value Estimate wholesale, retail, trade-in, and auction values for a vehicle by VIN, with optional mileage, state, and condition adjustments. Estimate a vehicle's current market value from a VIN. Use /v2/marketvalue for new integrations: it returns vehicle identity plus wholesale and retail values across condition tiers. Add mileage, state, and condition when you want the estimate adjusted for a specific vehicle and market. When to use it - Pricing inventory - Estimating trade-in value - Creating valuation workflows - Comparing clean, average, rough, and extra-clean value ranges - Adding valuation context after VIN decoding Parameters | Parameter | Required | Description | |---|---|---| | vin | Yes | The 17-character vehicle identification number | | key | Yes | Your CarsXE API key | | state | No | US state used for regional adjustment. Example: CA | | mileage | No | Current odometer mileage. Must be numeric | | condition | No | One of excellent, clean, average, or rough | If condition is omitted, use the returned condition buckets to choose the value range that matches your workflow. Example Response Top-level shape Click any value bucket to expand it and see sample data. For the full interactive reference, try it live in the API Reference. All response fields are optional. Missing value buckets mean the provider did not return that valuation for the VIN or market context. Valuation record identifier. Echo of request inputs and inferred country. Provider valuation publish date. Market region used for the valuation. Country used for the valuation. Vehicle model year. Manufacturer. Model name. Trim or series. Body style. Vehicle class. Wholesale values for a condition tier. Retail values for a condition tier. How to read value buckets Condition tiers - excellent, clean, average, and rough values | Suffix | Meaning | |---|---| | xclean | Excellent / extra-clean condition | | clean | Clean condition | | avg | Average condition | | rough | Rough condition | The request parameter condition=excellent maps conceptually to the xclean tier in the response. Value families - wholesale and retail buckets | Prefix | Meaning | |---|---| | whole_* | Wholesale-oriented valuation bucket | | retail_* | Retail-oriented valuation bucket | Adjustment fields - base value plus mileage, add/deduct, and regional adjustments The * is replaced by the value family and condition tier. For example, baseretailclean is the base retail value for a clean vehicle. Base valuation before mileage, equipment, or regional adjustments. Mileage adjustment applied to the valuation. Additions or deductions applied by the provider. Regional market adjustment. Errors | Status | When it happens | |---|---| | 400 | Missing VIN, wrong VIN length, invalid mileage, or invalid condition | | 401 | Missing or invalid API key | | 404 | No market value data found for this VIN | | 429 | Usage limit exceeded | | 500 | Internal server error | | 503 | Upstream market value provider unavailable | Valid condition values: See the Errors guide for general error handling guidance. Legacy v1 endpoint Use /v2/marketvalue for new integrations. Legacy /marketvalue still exists for older integrations and returns simpler fields such as retail, tradeIn, roughTradeIn, averageTradeIn, loanValue, msrp, tradeInValues, and auctionValues. --- ## Plate Decoder URL: /docs/products/plate-decoder Look up vehicle data by license plate number and state across 50+ countries. Resolve a license plate to structured vehicle data — make, model, trim, VIN, engine, and more. Pass a plate and state (or country) and get back the same richness you'd expect from a VIN decode, sourced directly from registration records. When to use it - Identifying a vehicle when you only have a plate number - Pre-filling vehicle details in insurance or dealership workflows - Augmenting camera-captured plates with spec data - Cross-referencing plate ownership against VIN history Parameters | Parameter | Required | Description | |---|---|---| | plate | Yes | The license plate number | | state | Yes | Two-letter state, province, or region code (e.g. CA, ON, NSW) | | key | Yes | Your CarsXE API key | | country | No | ISO 3166-1 alpha-2 country code. Defaults to US. Example: GB, DE, AU | | district | No | Pakistan only — pass the district code alongside country=PK | | require_vin | No | Spain only (country=ES). Pass 1 to guarantee a VIN in the response. Costs 2× a standard lookup | Example Response Top-level shape Click input to expand it and see the echoed request fields. For the full interactive reference, try it live in the API Reference. All fields except success and input are optional — availability depends on the country and provider. Country response matrix Plate Decoder v2 responses are country-specific. Expand a country below to inspect the JSON shape that country can return from the current v2 response builders. These fields are possible response keys, not guaranteed non-empty values for every plate. Fields Identity — Who made it, what it is, and its VIN Human-readable summary combining year, make, model, and trim. Example: "2021 Toyota Camry SE". Manufacturer or brand. Example: "Toyota", "Ford", "BMW". Model family. Example: "Camry", "F-150", "3 Series". Trim level or variant. Example: "SE", "XLT", "330i". Model year as a 4-digit string. Example: "2021". 17-character vehicle identification number, when available from the provider. Not guaranteed — use require_vin=1 with country=ES to enforce it for Spanish plates. Body & Style — Shape, body classification, and color Normalized vehicle category. Example: "Sedan", "SUV", "Truck". Optional — not always returned. Body style as recorded by the manufacturer, typically in uppercase with door count. Example: "SEDAN 4-DR", "PICKUP", "SPORT UTILITY 4-DR". Registered exterior color. Example: "Silver", "Black", "White". Sourced from registration records — may differ from the current painted color if the vehicle has been repainted. Powertrain — Engine, fuel, drivetrain, and transmission Full engine descriptor. Example: "2.5L L4 DOHC 16V". Optional — not always returned. Engine displacement in liters. Example: "2.5", "3.0", "5.0". Primary fuel type. Example: "Gasoline", "Diesel", "Electric", "Hybrid". Wheel drive configuration. Example: "FWD", "RWD", "AWD", "4WD". Transmission description. Example: "8-Speed Automatic", "6-Speed Manual", "CVT". Country where the vehicle was assembled. Example: "United States", "Germany", "Japan". Registration — Year registered Year the vehicle was first registered. May differ from the model year. Example: "2021". Optional — not always returned. Country & region support The endpoint supports 50+ countries. Pass country as an ISO 3166-1 alpha-2 code (e.g. GB, DE, NL, AU). It defaults to US when omitted. State or province is required for US, Australian, Canadian, and Pakistani plates — use the standard two-letter code (e.g. CA, NSW, ON). Pakistan additionally supports a district parameter for more precise lookups. Coverage and field availability vary by country. Some regions return a full spec set; others return only identity fields. See the full list of supported countries. require_vin (Spain only) By default, Spanish plate lookups use a standard provider that does not guarantee a VIN in the response. Pass require_vin=1 with country=ES to route the request through a higher-cost provider that always returns a VIN. This costs 2× a standard lookup and only applies to country=ES. Passing it for any other country has no effect. Errors | Status | When it happens | |---|---| | 400 | Missing plate or state, or invalid parameter values | | 401 | Missing or invalid API key | | 404 | No data found for this plate in the provider's database | | 429 | Usage limit exceeded | | 500 | Internal server error | | 503 | Upstream plate data provider unavailable | See the Errors guide for general error handling guidance. --- ## Recalls URL: /docs/products/recalls Check for open safety recalls associated with any VIN. Look up all open vehicle safety recalls for a vehicle by VIN. The response tells you how many recalls exist, whether a remedy is available, and the full detail of each campaign — component, risk, and fix instructions. Parameters | Parameter | Required | Description | |---|---|---| | vin | Yes | The 17-character vehicle identification number | | key | Yes | Your CarsXE API key | Example Response Top-level shape Click data or recalls to expand them and see sample values. For the full interactive reference, try it live in the API Reference. data All vehicle-level fields and the recall list are nested under data. Vehicle identity — make, model, year decoded from the VIN Unique identifier for this recall report record. Example: "d1269d6b-54a2-4bf3-8119-1c8fdb4f0563". The VIN used to look up this record. Example: "1C4JJXR64PW696340". The legal manufacturer name as registered for recall reporting. May differ from the brand name consumers know. Example: "FCA US LLC", "TOYOTA MOTOR MFG DE BAJA CALIFORNIA S DE RL DE CV". The vehicle brand. Example: "JEEP", "TOYOTA", "FORD". The model name. Example: "Wrangler", "Tacoma", "F-150". The 4-digit model year. Example: "2023". Vehicle category when returned by the data source. Example: "PASSENGER CAR", "TRUCK". Recall summary — whether recalls exist and how many ISO 8601 date when this recall report was generated. Example: "2024-09-27". true if at least one open recall was found for the VIN, false otherwise. Check this field before iterating recalls. Total number of recalls in the recalls array. Example: 1, 3. recalls[] Each item in the recalls array represents one open recall campaign. All fields are optional — a null value means the data source did not provide that information for this campaign. Identification — campaign ID, campaign type, and dates The campaign identifier. Example: "24V720". May be empty for voluntary service campaigns not filed as official safety campaigns. The manufacturer's internal recall campaign number. Example: "95B", "25TC07-28342". The type of recall campaign. Example: "NHTSA" for federally mandated campaigns, "VOLUNTARY/SERVICE" for manufacturer-initiated campaigns. A short descriptive name for the recall campaign as filed. Example: "2020-2024 JL & 2022-2024 WL PHEV High Voltage Battery". ISO 8601 date the recall was issued. Example: "2024-09-27". ISO 8601 date the recall expires, if applicable. null if the recall has no set expiration. Description — what component is affected and what the risk is The vehicle component or system covered by the recall. Example: "FUEL SYSTEM, GASOLINE", "AIR BAGS". May be empty for some voluntary campaigns. Full description of the defect or condition being recalled. This is the official text from the recall filing. Description of the safety risk posed by the defect — what could go wrong and what the consequences are. May be empty for non-safety campaigns. Remedy — fix availability, parts, labor, and urgency flags true if a fix is currently available at dealerships. null means the data source has not confirmed remedy availability. Description of the repair or corrective action. Example: "FCA US will conduct a voluntary safety recall. Remedy is a software flash followed by a HV battery replacement if needed.". true if repair parts are in stock at dealerships. null if unknown. Minimum estimated labor hours for the repair. null if not provided. Maximum estimated labor hours for the repair. null if not provided. true if dealers are prohibited from selling affected vehicles until the recall is remedied. null if the data source did not specify. true if owners are advised not to drive the vehicle until repaired. null if the data source did not specify. Current status of the recall campaign. Example: "Incomplete" (remedy not yet performed), "INCOMPLETE", "Complete". Errors | Status | When it happens | |---|---| | 400 | Missing VIN, or VIN is not exactly 17 characters | | 401 | Missing or invalid API key | | 404 | No recall data found for this VIN | | 429 | Usage limit exceeded | | 500 | Internal server error | See the Errors guide for general error handling guidance. --- ## Recognition URL: /docs/products/recognition Extract license plates and VINs from images using computer vision. Recognition turns vehicle images into structured identifiers you can use in the rest of the CarsXE API. Use Plate Image Recognition when the photo contains a license plate. Use VIN OCR when the photo contains a VIN plate, dashboard VIN, or sticker. Both endpoints are POST requests with JSON bodies and key as a query parameter. When to use it - Intake workflows where users upload vehicle photos - Parking, tolling, inspections, and fleet workflows - Turning a plate photo into a plate string before plate decoding - Extracting a VIN from paperwork, dashboard stickers, or VIN plates Plate Image Recognition Extract a license plate number and region from a vehicle image. Parameters | Parameter | Required | Location | Description | |---|---|---|---| | key | Yes | Query | Your CarsXE API key | | image_url | Yes | JSON body | Public URL to an image of a vehicle/license plate | Use imageurl for raw HTTP requests. Some SDKs may expose this as uploadurl; the endpoint body field remains image_url. Example Response Top-level shape Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference. All response fields are optional. If results is empty or missing, no plate was detected. results Best plate candidate, normalized as returned by the recognition provider. Example: "9djc652". Bounding box around the detected plate. Predicted plate region with code and score. Confidence for the selected plate candidate, from 0 to 1. Alternate plate readings and confidence scores. Detection confidence for the plate region. Vehicle detection details when available, including type, confidence, and vehicle bounding box. Bounding boxes Coordinates are pixel offsets in the original image. xmin and ymin mark the top-left corner. xmax and ymax mark the bottom-right corner. Use these values to draw overlays or crop the detected plate or vehicle. Left edge of the detected region. Top edge of the detected region. Right edge of the detected region. Bottom edge of the detected region. Region and candidates region - predicted registration region The region.code identifies the predicted plate region, such as "us-ca". The region.score value is the confidence for that region prediction, from 0 to 1. candidates - alternate plate readings Use candidates when the top plate result is ambiguous. Each candidate includes a possible plate string and a score so you can decide whether to show alternatives, ask for review, or accept the top result automatically. VIN OCR Extract a 17-character VIN from an image. Parameters | Parameter | Required | Location | Description | |---|---|---|---| | key | Yes | Query | Your CarsXE API key | | image_url | Yes | JSON body | Public image URL or base64-encoded image string | Example Response Top-level shape Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference. All response fields are optional. A successful response can include one best VIN plus candidate VINs when multiple readings are possible. VIN fields Best extracted VIN candidate. Example: "JHLRD77874C026456". Confidence score between 0 and 1. Bounding box around the detected VIN text. Alternate VIN candidates with confidence scores and optional bounding boxes. Image quality - Use a sharp image where the plate or VIN is readable. - Avoid glare, motion blur, extreme angles, and heavy cropping. - For VIN OCR, include the full VIN line when possible. - For base64 input on VIN OCR, send the base64 string in image_url. Chaining Recognition With Vehicle Data Plate Image Recognition returns a plate string; pass that into Plate Decoder when you need vehicle details. VIN OCR returns a VIN; pass that into Specifications, Market Value, Vehicle History, or Recalls. Use the API Reference to try these endpoints live and inspect the complete schemas. Errors See the Errors guide for the full list. Plate Image Recognition: - 400 - missing image URL, commonly "Missing upload URL". - 404 - no plate detected, commonly "No plates detected in image". - 500 - recognition service error, commonly "Could not get information at this time". VIN OCR: - 400 - missing image data, invalid image data, or no text detected. - 401 - API key is inactive. - 404 - API key not found/disabled, or no valid VIN candidates found. - 429 - usage limit exceeded. --- ## Specifications URL: /docs/products/specifications Decode any 17-character VIN and retrieve full vehicle specifications — make, model, year, engine, equipment, and more. Decode any 17-character VIN into structured vehicle data: identity, engine, transmission, dimensions, standard equipment, colors, and warranty information. For most use cases the default response is sufficient. Add deepdata=1 when you need extended vehicle data — it's slower but pulls additional fields not available from the primary source. Parameters | Parameter | Required | Description | |---|---|---| | vin | Yes | The 17-character vehicle identification number | | key | Yes | Your CarsXE API key | | deepdata | No | Pass 1 to include extended vehicle data under the deepdata key (adds latency) | | disableIntVINDecoding | No | Pass 1 to return a 404 instead of falling back to the international decoder for non-US VINs | | format | No | json (default) or xml | Example Response Top-level shape Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference. All response fields are optional. A field missing from attributes means that data isn't available for this VIN from the decoding source. attributes Identity — Who built it, what it is, and where it was made The 4-digit model year as assigned by the manufacturer — encoded in the 10th character of the VIN. This is the vehicle's official model year, which may differ from the calendar year it was produced or sold. Example: "2012". The manufacturer or brand name. This is the top-level brand, not the parent company — so a vehicle sold under "BMW" won't show "BMW Group". Example: "BMW", "Toyota", "Ford". The product line or model family. For vehicles with sub-variants, this is the family name. Example: "5 Series", "Camry", "F-150". The specific trim level or variant within the model. Trims define the feature set and often the price tier. Example: "535i", "XLT", "Limited". The body style as recorded by the manufacturer — typically in uppercase with door count. Example: "SEDAN 4-DR", "PICKUP", "SPORT UTILITY 4-DR". Normalized vehicle category. This is a standardized classification regardless of how the manufacturer labels it. Example: "Sedan/Saloon", "SUV", "Truck". Country where the vehicle was assembled — derived from the VIN's World Manufacturer Identifier (WMI). Example: "Germany", "United States", "Japan". City or region of the assembly plant. Example: "Dingolfing", "Georgetown", "Smyrna". Engine & Fuel — Powertrain specs, fuel type, and EPA fuel economy The full engine descriptor combining displacement, cylinder layout, valve configuration, and cam type. This is the most human-readable summary of the engine. Example: "3.0L L6 DOHC 24V". Engine displacement in liters, as a decimal string. Example: "3.0", "2.5", "5.0". Number of cylinders. Example: "4", "6", "8". Electric vehicles may return "0" or omit this field. Primary fuel the engine runs on. Example: "Gasoline", "Diesel", "Electric", "Flex Fuel (FFV)". Fuel tank capacity in gallons. Example: "18.50 gallon". Not applicable to electric vehicles. EPA-estimated fuel economy in city driving conditions. Example: "20 MPG". Based on the EPA's standard city drive cycle at time of manufacture. EPA-estimated fuel economy on the highway. Example: "30 MPG". Higher than city due to reduced stop-and-go. Transmission & Drivetrain — Gearbox type, speed count, and wheel drive configuration Full transmission description combining speed count and type. Example: "8-Speed Automatic", "6-Speed Manual". Abbreviated transmission code used in window stickers and build sheets. Example: "8A" (8-speed automatic), "6M" (6-speed manual). Transmission category. Example: "Automatic", "Manual", "CVT" (continuously variable), "DCT" (dual-clutch). Number of forward gears. Example: "6", "8", "10". CVTs may return "1". Wheel drive configuration. Example: "RWD" (rear-wheel drive), "FWD" (front-wheel drive), "AWD" (all-wheel drive), "4WD" (four-wheel drive with low range). Dimensions & Weight — Physical measurements and weight ratings Vehicle height from ground to roof in inches, measured without roof rack or antenna. Example: "58.00". Total vehicle length bumper-to-bumper in inches. Example: "193.90". Vehicle width in inches, excluding mirrors. Example: "73.90". Distance between the center of the front and rear axles in inches. Longer wheelbases generally mean more interior space and better ride stability. Example: "116.90". Weight of the vehicle in pounds with all standard equipment and fluids, but no passengers or cargo. Example: "3,869". The GVWR — the maximum total weight the vehicle is rated to handle, including the vehicle itself plus passengers and cargo. Example: "Class 1: 6000 lbs or less". Seating & Pricing — Passenger capacity and original factory pricing Number of doors, including a tailgate or hatchback if applicable. Example: "4", "2", "5" (hatchback). Standard passenger capacity as configured at the factory for this trim. Does not reflect aftermarket or optional seating changes. Example: "5", "7". The dealer invoice price at the time of manufacture — what the dealer paid before any markup or incentives. This is a historical figure and does not reflect current market value. Example: "$48,275 USD". The original sticker price set by the manufacturer at launch. Like invoice price, this is a historical figure from when the vehicle was built. Example: "$52,100 USD". equipment Each key in the equipment object is a snake_case feature name. The value is "Std." if the feature was standard on this trim, or an empty string if not. Common flags: absbrakes, driverairbag, passengerairbag, sideairbag, tractioncontrol, stabilitycontrol, leatherseat, navigationaid, powersunroof, backupcamera, bluetooth, alloywheels, keylessentry, remote_start. See the API Reference for the full list of 70+ flags. colors "Exterior" or "Interior". The manufacturer's color name for this option. Example: "Alpine White", "Black Dakota Leather". warranties Coverage type: "Basic" (bumper-to-bumper), "Powertrain", or "Rust" (corrosion perforation). Mileage limit for this warranty. Example: "50,000 mile" or "Unlimited". Time limit for this warranty from the original purchase date. Example: "48 month". Regional behavior US VINs are decoded via ClearVin and return the full attribute set described above. Non-US VINs automatically fall back to the international decoder, which returns a smaller set of fields (make, model, year, and a handful of others). If you need to suppress this fallback and receive a 404 instead of a partial response, pass disableIntVINDecoding=1. Extended data (deepdata) Pass deepdata=1 to include additional extended fields. This makes a second upstream call and adds latency — only use it when you need fields that aren't in the standard response. The extended data appears under the deepdata key as a flat string → string map: Key names are the raw extended-data variable names, not normalized. Availability varies by VIN. Errors See the Errors guide for the full list. The most common case specific to this endpoint: - 404 — "No data found for this VIN. Try a deep search by setting deepdata=1 in your request" — the VIN is valid but not in the primary database. Retry with deepdata=1 to run a deeper fallback decode. - 400 — "Missing vin (vehicle identification number)" or "Wrong VIN length, must be 17 characters" — fix the input, don't retry. --- ## Vehicle History URL: /docs/products/vehicle-history Retrieve comprehensive history reports including title records, salvage events, and insurance data. Retrieve a vehicle history report by VIN. The /history endpoint returns title records, brand records, junk and salvage events, insurance information, VIN change indicators, odometer readings, and historical title activity when available. History data depends on the records available from reporting sources and jurisdictions. Most integrations should treat the response as a set of optional record groups and handle missing or empty arrays gracefully. Parameters | Parameter | Required | Description | |---|---|---| | vin | Yes | The 17-character vehicle identification number | | key | Yes | Your CarsXE API key | | format | No | json (default) or xml | Example Response Top-level shape Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference. All response fields are optional. Empty or missing arrays mean CarsXE did not receive that record group for the VIN. junkAndSalvageInformation Junk and salvage records describe events reported by junk yards, salvage yards, recyclers, auctions, or similar reporting entities. These records are useful for identifying total-loss, salvage, export, or disposition activity. Reporting entity details, such as category, entity name, location, phone number, and contact email when available. Date the reporting entity obtained or recorded the vehicle. Example: "2016-12-06T00:00:00.000Z". Reported disposition for the vehicle. Example: "TO BE DETERMINED". Export intent flag from the source record. Example: "Y" or "N". Common fields inside ReportingEntityAbstract include ReportingEntityCategoryCode, IdentificationID, ReportingEntityCategoryText, EntityName, LocationCityName, LocationStateUSPostalServiceCode, TelephoneNumberFullID, and ContactEmailID. insuranceInformation Insurance records describe information reported by insurance carriers or related entities. Depending on the source record, this can include the reporting entity and the date the vehicle was obtained or reported. Insurance or reporting entity details, including name and location when available. Date associated with the insurance record. brandsInformation Brand records describe labels applied to the title or vehicle record, such as salvage, rebuilt, flood damage, collision, prior taxi, or other jurisdiction-defined brands. brandsRecordCount gives the number of brand records returned. Normalized brand name when the source provides one. Example: "Salvage". Source or brand code when available. Human-readable explanation of the brand. Brand payloads can include additional source-specific fields. currentTitleInformation Current title records describe the latest title information available for the VIN. Some records also include nested historical title details. Jurisdiction or state that issued the title. Example: "CA". Title issue date as an ISO timestamp. Odometer reading from the title record. Values may be zero-padded. Odometer unit code. Example: "M" for miles. Nested historical title records when included by the source. historyInformation Historical title records list prior title activity for the VIN. Use this array to build a title timeline, compare title jurisdictions, and inspect odometer readings across title events. VIN attached to the historical title record. Jurisdiction or state that issued the title. Historical title issue date as an ISO timestamp. Odometer reading recorded for the historical title. Odometer unit code. Example: "M" for miles. vinChanged vinChanged is a boolean indicator for whether the source reports a VIN change. A value of false means no VIN change was reported in the available data. How to read dates and odometer values Dates are returned as ISO timestamps. If your UI only needs the calendar date, display the date portion before T. Odometer readings may be returned as zero-padded strings, such as "000024806". Parse them as numbers only after preserving the original value if you need to show source data exactly. VehicleOdometerReadingUnitCode identifies the odometer unit. The examples on this page use "M" for miles. Data availability Vehicle history depends on reporting sources, jurisdiction coverage, and update timing. Empty or missing arrays mean no available records were returned from the source for that group; they are not a guarantee that no event ever occurred. Errors See the Errors guide for general error handling guidance. | Status | When it happens | |---|---| | 400 | Missing VIN or wrong VIN length | | 401 | Missing or invalid API key | | 403 | This API key has been blocked for the History API | | 404 | No history data found for this VIN | Common endpoint-specific messages: - 400 - "Missing vin (vehicle identification number)" or "Wrong VIN length, must be 17 characters" - fix the input before retrying. - 403 - "This API key has been blocked, please contact support if you believe this is an error." - contact support if the key should have access. - 404 - no history report is available for the VIN. --- ## Vehicle Images URL: /docs/products/vehicle-images Retrieve photos of any vehicle by make, model, and year — filter by angle, color, and size. Fetch real vehicle photos for any make and model. The endpoint searches the web for matching images, validates each one with AI to confirm it shows the right vehicle, and returns up to 10 results per call. Filter by angle, color, photo type, and size to get exactly the images your use case needs. Parameters | Parameter | Required | Description | |---|---|---| | make | Yes | Vehicle manufacturer. Example: "Toyota", "Ford", "BMW" | | model | Yes | Vehicle model name. Example: "Camry", "F-150", "3 Series" | | key | Yes | Your CarsXE API key | | year | No | 4-digit model year. Narrows results to a specific model year | | trim | No | Trim level. Helps surface images of the right variant | | color | No | Preferred vehicle color. Example: "red", "midnight blue" | | angle | No | front, side, or back | | photoType | No | exterior (default), interior, or engine | | size | No | Small, Medium, Large, Wallpaper, or All | | license | No | Filter by usage rights: Public, Share, ShareCommercially, Modify, or ModifyCommercially | | transparent | No | true (default) — prefer images with transparent/white backgrounds | | validate | No | true (default) — AI validates each image before including it in the response | | format | No | json (default) or xml | Example Response Top-level shape Click the query or images sections to expand them and see sample data. For the full interactive reference, try it live in the API Reference. The images array is always present. It will be empty if no matching images pass validation — not absent. images Each object in the images array represents one validated vehicle photo. The MIME type of the image file. Example: "image/jpeg", "image/png", "image/webp". Direct URL to the full-resolution image. Use this to display or download the image. URLs are sourced from the public web and may become unavailable over time — cache images on your end if persistence matters. URL of the web page where this image was found. Useful for attribution or linking users back to the original source. Image height in pixels. May be returned as a string or number depending on the source. Image width in pixels. May be returned as a string or number depending on the source. All images are at least 300px on their shortest side. File size in bytes. Useful for estimating download time or enforcing size limits before fetching the full image. URL to a smaller cached thumbnail of the image, hosted by Google. Faster to load than the full image — useful for previews and grids. Thumbnail height in pixels. Thumbnail width in pixels. AI validation By default, each image is validated by AI before being included in the response. The validator confirms the image shows the correct vehicle make, model, and year — images that don't match are dropped. Set validate=false to skip validation. This reduces latency but may return images that don't precisely match the requested vehicle. Errors See the Errors guide for the full list. The most common cases specific to this endpoint: - 400 — "Missing make" or "Missing model" — both parameters are required. Add them and retry. - 404 — No images found for this combination — try relaxing your filters (remove angle, color, or trim) or verify the make and model spelling. --- ## Year Make Model URL: /docs/products/year-make-model Look up vehicle data by year, make, and model, with optional OBD-II code decoding. Year Make Model includes two lightweight APIs for cases where you do not have a VIN. Use Year Make Model to find the best matching vehicle and trim from basic vehicle identity. Use the OBD-II code decoder to map diagnostic trouble codes to readable diagnosis text. Year Make Model Look up vehicle data by year, make, and model, with an optional trim hint. This is useful when a VIN is unavailable but you still need structured specs, colors, features, pricing, or trim options. Endpoint: /v1/ymm Parameters | Parameter | Required | Description | |---|---|---| | year | Yes | Vehicle model year, numeric, between 1900 and the current model year plus one | | make | Yes | Manufacturer, for example Toyota, Ford, or BMW | | model | Yes | Vehicle model, for example Camry, F-150, or X5 | | trim | No | Trim hint, for example XLE or Sport; fuzzy matched when possible | | allTrimOptions | No | Pass 1 to return all trim options for the year, make, and model | Example Response Top-level shape Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference. All response fields are optional except success. Availability varies by vehicle, trim, and source coverage. bestMatch The bestMatch object contains the matched vehicle and trim data. Vehicle manufacturer. Example: "Toyota". Vehicle model. Example: "Camry". Vehicle model year. Example: "2023". Full trim and body description for the matched vehicle. Example: "XLE 4dr Sedan (3.5L 6cyl 8A)". Original base manufacturer's suggested retail price when available. Original base dealer invoice price when available. Factory seating capacity for the matched trim. Available exterior and interior color options. Grouped feature and specification data, usually under standard. trimOptions When allTrimOptions=1 is passed, trimOptions returns available trims for the requested year, make, and model. Use this when users need to choose a trim before requesting the best match. color Color data is grouped by exterior and interior. Each item uses the same shape: Manufacturer color or upholstery name. Example: "Supersonic Red" or "Black, leather". Comma-separated RGB value. Example: "226,5,0". features Features are grouped into categories under features.standard. Feature category name. Example: "Power Feature", "Warranty", or "Measurements". List of feature items in this category. Each feature item has: Feature or measurement name. Example: "hands-free entry" or "Rear leg room". Value for the feature when the source provides one. Feature flags often return null; measurements usually return a string such as "38.0 in.". input The input object echoes the request values used for the lookup. It can include year, make, model, trim, and allTrimOptions. If trim is omitted, the API returns the best/default trim match for the year, make, and model. If trim is provided but not exact, the API attempts a close match. Pass allTrimOptions=1 when you need the available trims instead of a single best match. Response fields vary by vehicle and source availability. OBD-II Code Decoder Decode an OBD-II diagnostic trouble code into a readable diagnosis. Endpoint: /obdcodesdecoder Parameters | Parameter | Required | Description | |---|---|---| | code | Yes | OBD-II diagnostic trouble code, for example P0115 | | key | Yes | Your CarsXE API key | | format | No | json by default, or xml if supported by your endpoint configuration | Example For the full interactive reference, try it live in the API Reference. Response Whether the code was decoded. Diagnostic description for the trouble code. Lookup timestamp or date returned by the API. Normalized OBD code returned by the API. Errors See the Errors guide for the full list. Common Year / Make / Model errors: - 400 - Missing or invalid year, make, or model. - 404 - No vehicle matched the specified year, make, and model. - 500 - Could not fetch data. Common OBD-II code decoder errors: - 400 - Missing OBD code. - 500 - Could not find the requested code. Common errors for both endpoints: - 401 - API key is missing, invalid, disabled, or unauthorized. - 429 - Usage limit exceeded. --- ## SDKs URL: /docs/sdks Official CarsXE client libraries for every major language and platform. CarsXE provides official SDKs for all major languages. The CLI and MCP server let you query vehicle data from your terminal or wire CarsXE directly into AI editors like Claude Desktop, Cursor, and VS Code. Available libraries | Language / Tool | Package | Install | |---|---|---| | Node.js | @carsxe/sdk (npm) | npm install @carsxe/sdk | | Python | carsxe (PyPI) | pip install carsxe | | PHP | carsxe/carsxe (Packagist) | composer require carsxe/carsxe | | Ruby | carsxe (RubyGems) | gem install carsxe | | Go | carsxe-go-package | go get github.com/carsxe/carsxe-go-package | | Java | io.github.carsxe:carsxe (Maven) | implementation 'io.github.carsxe:carsxe:LATEST' | | Swift | carsxe (SPM) | Package URL: github.com/carsxe/carsxe-swift-package | | C# | carsxe (NuGet) | dotnet add package carsxe | | CLI | @carsxe/cli (npm) | npm install -g @carsxe/cli | | MCP Server | carsxe-mcp (npm) | npx -y carsxe-mcp | All API requests authenticate with your key as the key query parameter. Store it in an environment variable — never hardcode it. --- ## CLI URL: /docs/sdks/cli CarsXE command-line interface — query vehicle data from your terminal or AI agent. The @carsxe/cli package puts every CarsXE endpoint on the command line. Decode VINs, look up plates, pull recalls, and more — all from your terminal. Requires Node.js 22 or later. Installation Authentication Set your API key before running commands. The CARSXEAPIKEY environment variable takes priority over the saved config. You can also authenticate via browser: Commands Vehicle data Recognition Year Make Model Config Output formats By default the CLI prints a formatted, colorized summary. Use --table or --raw to change the output: | Flag | Output | |---|---| | (default) | Human-readable formatted output | | --table | ASCII table — good for quick comparison | | --raw | Compact JSON — pipe-friendly | Best practices Use the environment variable in CI/CD. Add CARSXEAPIKEY as a secret in GitHub Actions, CircleCI, or your deployment environment — don't rely on the saved config file in automated contexts. Combine --raw with jq for scripting: --- ## C# URL: /docs/sdks/csharp Official CarsXE SDK for C# and .NET. The carsxe NuGet package is the official CarsXE client for C# and .NET. It wraps the REST API with async methods and handles authentication. Requires .NET 6 or later. Installation Or via the NuGet Package Manager in Visual Studio: search for carsxe. Quick start Methods Core | Method | Description | |---|---| | Specs(params) | Decode a 17-character VIN into full vehicle specifications | | MarketValue(params) | Retail, trade-in, and auction value estimates | | Recalls(params) | Open safety recalls by VIN, make, model, or year | | PlateDecoder(params) | VIN lookup from a license plate (50+ countries) | | History(params) | Title events, salvage, junk, and insurance records | Bulk recall batch | Method | Description | |---|---| | SubmitBulkRecallBatch(params) | Submit a batch of VINs for recall lookup | | GetBulkRecallBatchStatus(batchId) | Poll job status | | GetBulkRecallBatchResults(batchId) | Retrieve completed results | | GetBulkRecallBatchDownloadUrl(batchId) | Get a CSV download URL | Error handling Methods throw Exception on API errors. Wrap calls in a try/catch block: Best practices Store your key in environment variables or .NET User Secrets for local development: Create one instance and reuse it. All methods are async — don't create a new CarsXE instance per request. In ASP.NET Core, register the client as a singleton via dependency injection: --- ## Go URL: /docs/sdks/go Official CarsXE SDK for Go. The carsxe-go-package module is the official CarsXE client for Go. It wraps the REST API with idiomatic methods and handles authentication. Requires Go 1.18 or later. Installation Quick start Methods Core | Method | Description | |---|---| | Specs(params) | Decode a 17-character VIN into full vehicle specifications | | MarketValue(params) | Retail, trade-in, and auction value estimates | | Recalls(params) | Open safety recalls by VIN, make, model, or year | | PlateDecoder(params) | VIN lookup from a license plate (50+ countries) | | History(params) | Title events, salvage, junk, and insurance records | Bulk recall batch | Method | Description | |---|---| | SubmitBulkRecallBatch(params) | Submit a batch of VINs for recall lookup | | GetBulkRecallBatchStatus(batchId) | Poll job status | | GetBulkRecallBatchResults(batchId) | Retrieve completed results | | GetBulkRecallBatchDownloadUrl(batchId) | Get a CSV download URL | Error handling Methods return an error value alongside the result. Always check before using the response: Best practices Read the key from the environment. Create one client and reuse it. The client manages connection pooling internally — creating a new instance per request bypasses that benefit. Store your key in an environment variable. Never hardcode it or commit it to source control. --- ## Java URL: /docs/sdks/java Official CarsXE SDK for Java. The carsxe artifact is the official CarsXE client for Java. It wraps the REST API with typed methods and handles authentication. Requires Java 11 or later. Installation Quick start Methods Core | Method | Description | |---|---| | specs(params) | Decode a 17-character VIN into full vehicle specifications | | marketvalue(params) | Retail, trade-in, and auction value estimates | | recalls(params) | Open safety recalls by VIN, make, model, or year | | platedecoder(params) | VIN lookup from a license plate (50+ countries) | | history(params) | Title events, salvage, junk, and insurance records | Bulk recall batch | Method | Description | |---|---| | submitBulkRecallBatch(params) | Submit a batch of VINs for recall lookup | | getBulkRecallBatchStatus(batchId) | Poll job status | | getBulkRecallBatchResults(batchId) | Retrieve completed results | | getBulkRecallBatchDownloadUrl(batchId) | Get a CSV download URL | Error handling Methods throw Exception on API errors. Wrap calls in a try/catch block: Best practices Validate the environment variable at startup. Create one instance and reuse it. The client manages connection pooling internally — don't instantiate per request. Store your key in an environment variable. Never hardcode it or commit it to source control. --- ## Node.js URL: /docs/sdks/node Official CarsXE SDK for Node.js and TypeScript. The @carsxe/sdk package is the official CarsXE client for Node.js and TypeScript. It wraps the REST API with typed methods, handles authentication, and throws structured errors. Requires Node.js 18 or later. Installation Quick start Methods Core | Method | Description | |---|---| | decodeVin(vin) | Decode a 17-character VIN into full vehicle specifications | | getMarketValue(params) | Retail, trade-in, and auction value estimates | | getRecalls(params) | Open safety recalls by VIN, make, model, or year | | decodePlate(params) | VIN lookup from a license plate (50+ countries) | | getVehicleHistory(vin) | Title events, salvage, junk, and insurance records | Bulk recall batch | Method | Description | |---|---| | submitBulkRecallBatch(params) | Submit a batch of VINs for recall lookup | | getBulkRecallBatchStatus(batchId) | Poll job status | | getBulkRecallBatchResults(batchId) | Retrieve completed results | | getBulkRecallBatchDownloadUrl(batchId) | Get a CSV download URL | Error handling All methods throw on non-2xx responses. Wrap calls in try/catch: Best practices Create one instance and reuse it. The client reuses the underlying fetch connection pool — instantiating per-request wastes resources. Store your key in an environment variable. Never hardcode it or commit it to source control. TypeScript types are included. The package ships full .d.ts declarations — no @types package needed. All response shapes (VehicleSpec, MarketValue, Recall, etc.) are exported directly from @carsxe/sdk. --- ## PHP URL: /docs/sdks/php Official CarsXE SDK for PHP. The carsxe/carsxe Packagist package ships typed PHP 8.1 model classes for all CarsXE API responses. It does not bundle an HTTP client — use it alongside Guzzle (or any PSR-18 client) to make requests and hydrate the typed models from the JSON response. Requires PHP 8.1 or later. Installation Quick start Available models | Class | Description | |---|---| | VehicleSpec | Full vehicle specification (VIN, make, model, engine, etc.) | | BulkRecallBatchJob | Completed bulk recall batch job | | BulkRecallBatchJobPending | In-progress bulk recall batch job | | BulkRecallBatchResult | Result row for a single VIN in a batch | | BulkRecallBatchRow | Raw recall row within a batch result | Each class exposes a static fromArray(array $data): self factory method that maps the API response directly to typed readonly properties. Additional endpoints The same Guzzle pattern works for every CarsXE endpoint — just change the path and query parameters: Error handling Guzzle throws GuzzleHttp\Exception\ClientException on 4xx responses and GuzzleHttp\Exception\ServerException on 5xx: Best practices Load your key from the environment. Never hardcode it. Reuse the Guzzle client. Instantiate it once (e.g. in a service container) and inject it — Guzzle reuses the underlying cURL handle pool. --- ## Python URL: /docs/sdks/python Official CarsXE SDK for Python. The carsxe package is the official CarsXE client for Python. It is async-first, built on httpx and pydantic v2. Requires Python 3.9 or later. Installation Quick start The client is an async context manager. Use async with so the underlying HTTP connection is closed when you're done. If you need to reuse the client across many calls (e.g. in a long-running server), instantiate it directly and call await client.close() when done instead. Methods Core | Method | Description | |---|---| | decode_vin(vin) | Decode a 17-character VIN into full vehicle specifications | | getmarketvalue(vin, *, mileage, state, condition) | Retail, trade-in, and auction value estimates | | get_recalls(*, vin, make, model, year) | Open safety recalls — pass VIN or make/model/year | | decode_plate(plate, state) | VIN lookup from a license plate (50+ countries) | | getvehiclehistory(vin) | Title events, salvage, junk, and insurance records | Bulk recall batch | Method | Description | |---|---| | submitbulkrecallbatch(vins, *, csv, csvurl, webhook_url) | Submit a batch of VINs | | getbulkrecallbatchstatus(batch_id) | Poll job status | | getbulkrecallbatchresults(batch_id) | Retrieve completed results | | getbulkrecallbatchdownloadurl(batchid) | Get a CSV download URL | Error handling By default the client raises CarsXEError on non-2xx responses. The exception carries status_code, code, and message. Pass throwonerror=False to suppress exceptions and inspect result.error instead: Best practices Always use async with or call close(). The SDK uses an httpx.AsyncClient internally — leaving it open leaks connections. Store your key in an environment variable. Reuse the client. In a web server (FastAPI, Django async views), create the client once at startup and close it on shutdown — don't instantiate per-request. --- ## Ruby URL: /docs/sdks/ruby Official CarsXE SDK for Ruby. The carsxe gem is the official CarsXE client for Ruby. It wraps the REST API with idiomatic methods and handles authentication. Requires Ruby 2.7 or later. Installation Add to your Gemfile: Or install directly: Quick start Methods Core | Method | Description | |---|---| | specs(params) | Decode a 17-character VIN into full vehicle specifications | | market_value(params) | Retail, trade-in, and auction value estimates | | recalls(params) | Open safety recalls by VIN, make, model, or year | | plate_decoder(params) | VIN lookup from a license plate (50+ countries) | | history(params) | Title events, salvage, junk, and insurance records | Bulk recall batch | Method | Description | |---|---| | submitbulkrecall_batch(params) | Submit a batch of VINs for recall lookup | | getbulkrecallbatchstatus(batch_id) | Poll job status | | getbulkrecallbatchresults(batch_id) | Retrieve completed results | | getbulkrecallbatchdownloadurl(batchid) | Get a CSV download URL | Error handling The client raises StandardError on API errors. Wrap calls in a begin/rescue block: Best practices Load your key from the environment. Use ENV.fetch to surface misconfiguration immediately: Create one instance and reuse it across requests — the client manages the underlying connection pool. Store your key in an environment variable. Never hardcode it or commit it to source control. --- ## Swift URL: /docs/sdks/swift Official CarsXE SDK for Swift. The carsxe package is the official CarsXE client for Swift. It wraps the REST API with idiomatic methods and handles authentication. Requires Swift 5.5 or later. Installation Quick start Methods Core | Method | Description | |---|---| | specs(_:) | Decode a 17-character VIN into full vehicle specifications | | marketValue(_:) | Retail, trade-in, and auction value estimates | | recalls(_:) | Open safety recalls by VIN, make, model, or year | | plateDecoder(_:) | VIN lookup from a license plate (50+ countries) | | history(_:) | Title events, salvage, junk, and insurance records | Bulk recall batch | Method | Description | |---|---| | submitBulkRecallBatch(_:) | Submit a batch of VINs for recall lookup | | getBulkRecallBatchStatus(_:) | Poll job status | | getBulkRecallBatchResults(_:) | Retrieve completed results | | getBulkRecallBatchDownloadUrl(_:) | Get a CSV download URL | Error handling Methods throw on API errors. Use do/catch: Best practices Read the key from the environment or Keychain. For iOS/macOS apps, store the key in the Keychain rather than environment variables for production use. Create one instance and reuse it — don't instantiate the client per request. Store your key in an environment variable for development: --- ## API Changelog Preview URL: /docs/changelogs/2026-06-17 A sample changelog entry for testing the generated CarsXE changelog pages. Added - Enabled the generated changelog section in the CarsXE docs navigation. - Added a sample release entry so the changelog listing and detail page can be reviewed. - Verified that changelog entries are sourced from dated folders under app/docs/changelog. Improved - The docs sidebar can now surface product updates alongside Documentation and API Reference. - Changelog pages use the existing Farm Labs timeline, metadata, search, and detail layout. Notes This is sample content for visual testing. Replace it with real release notes before publishing production updates. ---