The record behind
the vehicle.

Start with a real request.

Edit the query, then run it against this origin. The free vehicle lookup uses a shared, rate limited demo quota. Compare and listing examples require your own key. Responses include the HTTP status, elapsed time and current rate-limit window.

{ "status": "ready" }

{ "status": "ready" }

{ "status": "ready" }

Small surface. Explicit fields.

Authorization: Bearer <key>
Accept: application/json

GET /v1/demo/vehicle_risk

Rate limited free lookup for trying the API, with make, model and year. No credential needed. Visitors share the demo quota. Real use needs a key.

GET /v1/vehicle_risk

Required: make and model (trimmed, 1–64 characters), year (2000–2027). Model spellings resolve through stored model mappings, then an exact family key. Unknown vehicles return 404 and up to ten database suggestions.

GET or POST /v1/compare_vehicles

GET: vehicles=toyota:rav4:2018,honda:cr-v:2018 (URL-encode the query). POST: {"vehicles":[{"make":"Toyota","model":"RAV4","year":2018},{"make":"Honda","model":"CR-V","year":2018}]}. Supply 2–5 vehicles, bounded by the plan’s max_compare. Each vehicle costs one unit. Unresolved items are marked not_found and remain unrated.

GET /v1/listing_changes

Optional: make, model, year, uppercase 17-character vin, event_type (new, price_drop, relisted, delisted), inclusive since and until (YYYY-MM-DD), limit (1–200; default 50), cursor. Reuse next_cursor with the same filters. Newest date first, then descending event id. No active collectors returns an empty feed on a fresh database.

GET /v1/usage

Your plan and current UTC minute, day and month counters. This endpoint does not charge usage. Unknown and duplicate query parameters on data routes are rejected.

Read the data precisely.

Limits you can inspect.

These plans are read from this database on every page request. Vehicle and listing calls cost one unit; comparisons cost the number of requested vehicles. Input errors cost nothing. Admitted requests, including not-found results, increment all three UTC counters together. Over-limit requests do not change counters or daily accounting.

X-RateLimit-Limit, Remaining and Reset describe the window with the lowest fraction remaining (earliest reset breaks ties). Reset is a Unix timestamp in seconds. X-RateLimit-Window names it. Public discovery and unauthenticated responses use 0 / 0 / 0 and window none. The demo lookup reports shared plan headers. A 429 adds Retry-After in seconds until the earliest exceeded window resets; another exceeded window may still block the next call.

Errors are structured, too.

HTTP errors use RFC 9457 application/problem+json with a stable code. Input problems list field names without echoing values. MCP uses a JSON-RPC error envelope; tool failures carry the problem in error.data. Binding denials use problem+json and Retry-After.

{
  "type": "urn:carindex:problem:vehicle_not_found",
  "title": "vehicle not found",
  "status": 404,
  "detail": "No vehicle matches the supplied make, model and year.",
  "code": "vehicle_not_found",
  "suggestions": []
}

400 invalid input · 401 missing/invalid/revoked key · 403 MCP unavailable on plan · 404 unknown route or vehicle · 405 method not allowed · 413 body too large · 415 wrong media type · 429 cap exceeded · 500 internal error · 503 service or data unavailable. Public request bodies are capped at 64 KB.

The same data, through MCP.

Endpoint: https://api.theusedcarindex.com/mcp. Stateless Streamable HTTP, POST only, JSON responses. initialize, ping and tools/list are public; tools/call requires a key and consumes the same quota as HTTP. No session id or SSE subscription is required.

{
  "mcpServers": {
    "carindex": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.theusedcarindex.com/mcp",
        "--header",
        "Authorization: Bearer <key>"
      ]
    }
  }
}

{
  "url": "https://api.theusedcarindex.com/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer <key>",
    "Accept": "application/json, text/event-stream"
  }
}

Read-only tools: vehicle_risk {make, model, year}, compare_vehicles {vehicles}, listing_changes {make?, model?, year?, vin?, event_type?, since?, until?, limit?, cursor?}. Each returns JSON text and matching structuredContent, without a verdict.