DOCSEARCHbyAlgolia
Submit Docs

CarsXE Vehicle Data API Documentation

website·Indexed 33 days ago

https://docs.carsxe.com

Official documentation for the CarsXE Vehicle Data API, featuring guides on VIN decoding, vehicle specifications, and ownership lookups. Includes specialized resources for AI agents, such as an MCP server for AI tools, agentic payment flows using HTTP 402, and machine-readable documentation via llms.txt.

Tokens
16.2K
Snippets
54
Records
123
Agent score
63%

What's inside CarsXE

  1. Integrate CarsXE vehicle data with AI and automation tools

    CarsXE provides official integrations to connect vehicle data into AI agents, data platforms, data warehouses, and no-code automation platforms. Depending on the use case, users can utilize the Model Context Protocol (MCP) for AI tools, dedicated SDKs for custom development, or the general integrations suite.

  2. Integrate CarsXE with AI editors using the MCP server

    The CarsXE MCP server is the recommended integration path for interactive AI editors and chat clients such as Claude Desktop, Cursor, VS Code, and Windsurf. This server exposes all CarsXE endpoints as named tools and automatically formats responses as Markdown for the AI agent.

  3. Interpret the 402 Payment Required response body

    When a 402 error is returned due to insufficient credits, the response body provides details about the credit deficit.
    {
  "success": false,
  "message": "Insufficient credits. Add credits or enable auto-recharge to continue.",
  "credits": {
    "available": 12, // Credits in the wallet when the request was checked
    "cost": 25,       // Credits this request would have consumed (per-call cost × units)
    "remaining": 12   // Credits left after the attempt (unchanged from available for denied requests)
  }
}

  4. Process Vehicle Recalls in Batch using x402

    To process vehicle recalls in batch via the x402 payment flow, submit a JSON array of vins to /v1/recalls-batch/submit.

    Billing Logic: Duplicate VINs are normalized and charged only once. The total cost is calculated as the current per-VIN starter price multiplied by the count of unique VINs.

    Retrieving Results:

    1. A successful submission returns a 202 response containing a data.batchToken.
    2. This token must be kept secret and used in the X-CarsXE-Batch-Token header for subsequent requests to retrieve status, results, or downloads.
    3. Follow-up calls using the batch token do not require additional x402 payments.
    # Example: Checking the status of a batch request
curl -G "https://api.carsxe.com/v1/recalls-batch/status" \
  -d batchId=brb_mnablbn7_wvbaqv \
  -H "X-CarsXE-Batch-Token: <batch-token>"

  5. Implement best practices for agentic vehicle data workflows

    When implementing agentic workflows for vehicle payments and data retrieval, follow these architectural guidelines:

    • Identifier Management: Pass identifiers explicitly between API calls. For example, if a license plate lookup returns a VIN, use that specific VIN for all subsequent VIN-based product requests.
    • Error Handling: If identifiers are missing or ambiguous, branch your logic to handle the gap rather than sending an invalid request to a downstream endpoint.
    • Data Availability: Handle 'unavailable-data' responses according to the specific product guide for that endpoint.
    • Scaling: Use asynchronous batch products when dealing with large inventories and strictly adhere to defined rate limits and quotas.
    • Caching Strategy: Cache stable vehicle identity data to improve performance, but ensure time-sensitive data (such as market value or active recalls) is refreshed based on business requirements.

  6. Implement the CarsXE Agentic Payment retry flow

    When an AI agent encounters a 402 Payment Required response from the CarsXE API, it must follow these specific constraints to successfully complete the paid retry:

    1. Remove API Keys: Do not include the key parameter when making the request for the x402 payment flow.
    2. Maintain Parameter Consistency: Ensure all request parameters remain identical between the initial unpaid request and the subsequent paid retry.
    3. Extract Payment Details: Parse the 402 response body to determine the current price and the required network for payment.
    4. Use Correct Endpoint: Use the exact endpoint path specified in the payment requirement provided by the API.
    5. Deliver Final Result: Once the paid retry succeeds, return the resulting CarsXE API data directly to the end user.

  7. Increase API usage limits and volume

    To increase the included volume for API calls, users can take the following actions based on their needs:

    • Upgrade Tier: Move to a higher plan to increase the included volume across all APIs. Refer to the pricing page for plan comparisons.
    • Enable Overage Billing: Prevent API blocks by enabling overage billing. Usage exceeding the included volume is billed at the current tier's rate (calculated per call or per result, depending on the specific API).
    • Enterprise Plan: For high or spiky volume requirements, Enterprise plans provide custom quotas, custom pricing, and consolidated monthly invoicing.

  8. Implement error handling and retries for CarsXE API

    When making requests to the CarsXE API, you should branch your error handling based on the HTTP status code category.

    • 4xx Errors (Client Errors): Do not retry. These errors (including 429 Too Many Requests/Quota exceeded) indicate a problem with the request or account quota that requires a manual fix or plan upgrade.
    • 5xx Errors (Server Errors): Implement exponential backoff. These are transient server-side issues where retrying after a delay may succeed.

    Recommended strategy: Check response.ok or the status code first, then apply exponential backoff only for status codes $\ge 500$.

    import { CarsXE } from "carsxe-api";

const carsxe = new CarsXE("YOUR_API_KEY");

async function carsxeRequest(vin, { retries = 3 } = {}) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      return await carsxe.specs({ vin });
    } catch (error) {
      // 4xx: fix the request (or your quota) — retrying won't help
      if (error.statusCode < 500) throw error;

      // 5xx: exponential backoff
      if (attempt < retries) {
        await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      }
    }
  }
  throw new Error("CarsXE request failed after retries");
}

  9. Implement a Plate-to-Quote or Appraisal workflow

    To start an insurance quote, trade-in form, or appraisal using a license plate instead of a manually entered VIN, follow this sequence of API calls:

    1. Collect the vehicle's plate and its associated state, province, or country.
    2. Use the Plate Decoder to retrieve the VIN.
    3. Use the Specifications API to decode the retrieved VIN and confirm the vehicle's identity and equipment.
    4. Send the VIN, mileage, state, and condition to the Market Value API to determine the vehicle's value.
    5. (Optional) Integrate the Recalls API if safety status is required for the quote or appraisal decision.

    Critical Constraint: Never make valuation or underwriting decisions based solely on a plate response if the workflow requires a VIN. Always validate the resolved identity and implement a fallback path for cases where the Plate Decoder cannot return a VIN.

    Plate Decoder -> Specifications -> Market Value
                              `-> Recalls (optional)