carsxe

# CarsXE Skill CarsXE provides a REST API for comprehensive vehicle data. All endpoints are at `https://api.carsxe.com` and require an API key passed as `?key=YOUR_API_KEY`. > **API Key setup**: The user must have a CarsXE API key from https://api.carsxe.com/dashboard/developer. > If no key is configured, ask the user to provide it before making any API calls. See `references/api-reference.md` for full endpoint details, parameters, and response formats. --- ## Quick API Map | User intent | Endpoint | Parameters | |---|---|---| | Decode a VIN / get specs | `GET /specs` | `vin` | | Decode a license plate | `GET /platedecoder` | `plate`, `country` (required), `state` (optional) | | Market value | `GET /marketvalue` | `vin` | | Vehicle history report | `GET /history` | `vin` | | Vehicle images | `GET /images` | `make`, `model` + optional filters | | Safety recalls | `GET /recalls` | `vin` | | Lien & theft check | `GET /lientheft` | `vin` | | International VIN | `GET /internationalvin` | `vin` | | Year/Make/Model lookup | `GET /ymm` | `year`, `make`, `model`, optional `trim` | | OBD code diagnosis | `GET /obd` | `code` | | VIN OCR from image | `POST /vinocr` | `imageUrl` in JSON body | | Plate OCR from image | `POST /platerecognition` | `imageUrl` in JSON body | --- ## Workflow ### 1. Authenticate Always confirm or ask for the API key before making requests. The key is passed as a query param: ``` https://api.carsxe.com/specs?key=USER_API_KEY&vin=WBAFR7C57CC811956 ``` ### 2. Choose the right endpoint Match the user's query to the table above. When context is ambiguous: - VIN provided → prefer `/specs` first, then chain to other endpoints as needed - Plate provided → use `/platedecoder` to resolve VIN, then chain if needed - Make/Model/Year only → use `/ymm` or `/images` - OBD code (P/C/B/U + digits) → use `/obd` - Image URL provided → use `/vinocr` or `/platerecognition` (POST) ### 3. Chain requests when helpful A common power workflow: plate → VIN → specs + history + recalls in parallel. Example: *"Is this plate stolen and does it have open recalls?"* 1. `GET /platedecoder` → extract VIN 2. In parallel: `GET /lientheft` + `GET /recalls` ### 4. Present results Format output clearly with sections per API call. Use Markdown tables or lists for specs, highlight important findings (open recalls, theft records, salvage titles) prominently. --- ## Error Handling | HTTP Status | Meaning | Action | |---|---|---| | 401 / `invalid key` | Bad or missing API key | Ask user to check their key | | 404 / `no results` | VIN/plate not found in database | Inform user, suggest double-checking | | 429 | Rate limit exceeded | Wait and retry, inform user | | 5xx | Server error | Retry once, then report error | Always check the `error` field in JSON responses — CarsXE sometimes returns HTTP 200 with an error body. --- ## Examples **"What are the specs for VIN WBAFR7C57CC811956?"** → `GET https://api.carsxe.com/specs?key=KEY&vin=WBAFR7C57CC811956` **"Decode California plate 7XER187"** → `GET https://api.carsxe.com/platedecoder?key=KEY&plate=7XER187&state=CA&country=US` **"What's my car worth? VIN WBAFR7C57CC811956"** → `GET https://api.carsxe.com/marketvalue?key=KEY&vin=WBAFR7C57CC811956` **"Does this car have any recalls? 1C4JJXR64PW696340"** → `GET https://api.carsxe.com/recalls?key=KEY&vin=1C4JJXR64PW696340` **"My check engine light shows P0300"** → `GET https://api.carsxe.com/obd?key=KEY&code=P0300` **"Extract the VIN from this photo: https://example.com/vin.jpg"** → `POST https://api.carsxe.com/vinocr?key=KEY` with body `{"imageUrl":"https://example.com/vin.jpg"}` --- ## Reference Files - `references/api-reference.md` — Full parameter lists, response field descriptions, and edge cases for all 11 endpoints. Read this when you need exact field names or want to use optional filters.