openclaw/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.