# MarketCheck API: conventions for coding agents Drop this file into your project root so your AI coding assistant knows how the MarketCheck API behaves. Fetch the latest copy any time: ```bash curl -O https://developers.marketcheck.com/AGENTS.md ``` ## Base URL and authentication - Base URL: `https://api.marketcheck.com/v2` - Authentication is ALWAYS the `api_key` query parameter, never a header: `?api_key=YOUR_API_KEY` on every request. - Get a key at https://developers.marketcheck.com (free tier available). Read the key from an environment variable; never commit it. Quickstart: ```bash curl "https://api.marketcheck.com/v2/search/car/active?api_key=$MARKETCHECK_API_KEY&make=Toyota&model=Camry&zip=30301&radius=50&rows=10" ``` ## Machine-readable references - OpenAPI 3.1 spec (every endpoint, every parameter, real examples): https://developers.marketcheck.com/openapi.json - Docs index for LLMs: https://docs.marketcheck.com/llms.txt and https://docs.marketcheck.com/llms-full.txt - Any documentation page returns raw markdown when you append `.md` to its URL. - Docs MCP server (free, no key; search + endpoint reference inside your assistant): `https://developers.marketcheck.com/api/docs-mcp` - Claude Code: `claude mcp add --transport http marketcheck-docs https://developers.marketcheck.com/api/docs-mcp` - Cursor (`.cursor/mcp.json`): `{"mcpServers":{"marketcheck-docs":{"url":"https://developers.marketcheck.com/api/docs-mcp"}}}` - Live data MCP server (needs an account): see https://developers.marketcheck.com/mcp ## Pagination: get this right - `start` is the offset, `rows` is the page size. `rows` maxes out at 50; values above 50 silently fall back to the default of 10. - `num_found` in the response is the total match count. - Paging past your plan's deep-pagination limit (or past `num_found`) returns HTTP 422. Treat 422 during pagination as "end of results", not as a retryable error. - Deep pagination is slow by design. For bulk extraction use the data feeds product instead of paging the search API. ## Rate limits and retries | Plan | Monthly calls | Rate | |---|---|---| | Free | 500 | 5 rps | | Basic | 5,000 | 5 rps | | Standard | pay as you go | 40 rps | | Enterprise | custom | custom | - Server timeout is 120 seconds. - On HTTP 429, honor the `Retry-After` header (seconds). It can be very large when the MONTHLY quota is exhausted rather than the per-second rate: distinguish `RateLimit-*` headers (per-second window) from `Quota-*` headers (monthly quota) before deciding to wait. - Watch `RateLimit-Remaining` and `Quota-Remaining` proactively instead of driving into 429s. - Retry 5xx with exponential backoff. Never retry 4xx except 429. ## Request conventions - `country` defaults to `us`. Pass `country=ca` for Canada or `country=all`. - `dedup=true` is the default: one listing per VIN. Pass `nodedup` to see every listing of a VIN. - Range parameters are `min-max` strings, e.g. `price_range=5000-15000`, `year_range=2018-2022`. Open ends are allowed: `price_range=10000-`. - Timestamps (`*_at` fields) are unix epoch seconds. Distances are miles. Prices are USD for US listings, CAD for Canadian, GBP on UK endpoints. - Facets and stats: `facets=make,model` and `stats=price,miles` aggregate without fetching rows; combine with `rows=0` for pure aggregation calls. ## Errors - 401: missing or invalid `api_key`. - 404: no resource with that identifier (VIN or listing id). - 422: validation failure, including deep-pagination overflow (see above). - 429: rate limit or quota exceeded (see above). - 5xx: transient; retry with backoff. ## Key endpoints | Method | Path | Purpose | Docs | |---|---|---|---| | GET | `/v2/search/car/active` | Inventory Search | [docs](https://docs.marketcheck.com/docs/api/cars/inventory/inventory-search) | | GET | `/v2/search/car/recents` | Past Inventory Search | [docs](https://docs.marketcheck.com/docs/api/cars/inventory/past-inventory-search) | | GET | `/v2/search/car/auction/active` | Auction Search | [docs](https://docs.marketcheck.com/docs/api/cars/inventory/auction-search) | | GET | `/v2/listing/car/{listing_id}` | Car Listing Details | [docs](https://docs.marketcheck.com/docs/api/cars/vehicle-listing/car-listing) | | GET | `/v2/history/car/{vin}` | History by VIN | [docs](https://docs.marketcheck.com/docs/api/cars/vehicle-history/history-by-vin) | | GET | `/v2/decode/car/{vin}/specs` | Basic VIN Decoder | [docs](https://docs.marketcheck.com/docs/api/cars/vehicle-specs/basic) | | GET | `/v2/decode/car/neovin/{vin}/specs` | NeoVIN Decoder | [docs](https://docs.marketcheck.com/docs/api/cars/vehicle-specs/neovin) | | GET | `/v2/predict/car/us/marketcheck_price` | MarketCheck Price™: API Tiers & Endpoints | [docs](https://docs.marketcheck.com/docs/api/cars/market-insights/marketcheck-price) | | GET | `/v2/predict/car/us/marketcheck_price/comparables` | MarketCheck Price™: API Tiers & Endpoints | [docs](https://docs.marketcheck.com/docs/api/cars/market-insights/marketcheck-price) | | GET | `/v2/dealers/car` | Dealers Search | [docs](https://docs.marketcheck.com/docs/api/cars/dealerships/dealers-search) | | GET | `/v2/dealerships/car` | Dealerships Search | [docs](https://docs.marketcheck.com/docs/api/cars/dealerships/dealerships) | | GET | `/v2/sales/car` | Inferred Sales Stats | [docs](https://docs.marketcheck.com/docs/api/cars/market-insights/inferred-sales-stats) | | GET | `/v2/search/car/auto-complete` | Auto-Complete | [docs](https://docs.marketcheck.com/docs/api/cars/inventory/auto-complete) | | GET | `/v2/search/car/uk/active` | Inventory Search | [docs](https://docs.marketcheck.com/uk/docs/api/cars/inventory/inventory-search) | | POST | `/v2/marketmatch/dealers/rank` | MarketMatch: Rank Dealers for a Vehicle | [docs](https://docs.marketcheck.com/docs/api/cars/market-insights/marketmatch) | The full list (73 endpoints) is in the OpenAPI spec and in the docs MCP's `list_endpoints` tool. ## Data usage policies Caching, retention, field display, and image usage rules are contractual. Do not infer them: see https://developers.marketcheck.com/terms and ask api@marketcheck.com when unsure.