CarValuator

Valuation API

White-label used-car valuations as a REST API. Send a VIN, a make/model, or a photo — get back a structured resale valuation you render in your own product, under your own brand. v1

On this page: Quick start Authentication Endpoint Response Errors & limits Access OpenAPI

Quick start

Every request is a POST to /v1/valuation with your API key as a bearer token. Start with a free sandbox key (cvk_test_…), which returns realistic sample data at no charge, then swap to your live key.

# Value a car by VIN
curl https://api.carvaluator.app/v1/valuation \
  -H "Authorization: Bearer cvk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "vin": "1HGCM82633A004352" }'

Authentication

Send your key on every request:

Authorization: Bearer cvk_live_xxxxxxxx      // preferred
x-api-key: cvk_live_xxxxxxxx                  // also accepted

Keep live keys server-side — never ship them in a browser or mobile app. Keys are per-client and can be revoked or re-planned instantly. Ask us for a sandbox key to begin.

Endpoint

POST /v1/valuation

Provide at least one identifying input: a vin, a make+model, or a photoBase64.

Field	Type	Notes
`vin`	string	17-character VIN. Decoded automatically.
`make`	string	e.g. Honda
`model`	string	e.g. Accord
`year`	integer	Model year.
`mileage`	integer	Odometer, miles.
`condition`	string	Free text: clean, fair, rough…
`photoBase64`	string	Base64 photo of the car or VIN plate (optional).
`lang`	string	`en` or `es` for the insight text. Default `en`.

Response

A stable JSON contract — safe to build against; breaking changes ship as /v2.

{
  "identified": true,
  "car": { "year":2015, "make":"Honda", "model":"Accord",
           "mileage":82000, "condition":"clean" },
  "value": { "low":13200, "mid":14800, "high":16500, "currency":"USD" },
  "sources": [ { "name":"Auction comps", "price":14500, "note":"…" } ],
  "marketInsights": "…",
  "recommendation": "…",
  "requestId": "req_8f2c1a0b9d3e"
}

Always keep requestId in your logs — quote it if you contact support about a call.

If a vehicle can't be recognized, the call still returns 200 with identified: false (not an error) — check that field before using value.

Errors & rate limits

Errors are JSON with a machine-readable error and a human message. Every response carries usage headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute.
`X-RateLimit-Remaining`	Requests left this minute.
`X-RateLimit-Reset`	Seconds until the window resets.
`X-Quota-Limit / -Used / -Remaining`	Your monthly allotment and usage.

Status	error	Meaning
401	`unauthorized`	Missing / invalid / revoked key.
402	`quota_exceeded`	Monthly quota reached — upgrade or contact sales.
502	`valuation_failed`	Engine couldn't return a valuation — retry.
429	`rate_limited`	Slow down; honor `Retry-After`.
400/413	`invalid_*`	Bad body or oversized photo.
503	`unavailable`	Transient — retry shortly.

Access

Sandbox keys are free (cvk_test_…) — they return sample data so your team can build and test the integration with no commitment. Ask us and we'll issue one.

Production access is provided under a licensed API key, including white-label enterprise licensing (your brand, our engine, with an SLA). Pricing scales with your volume — tell us your expected monthly valuations and we'll put a proposal together.

Ready to start or want a quote? contact@carvaluator.app

OpenAPI specification

Machine-readable spec for code generation and Postman/Insomnia import:

/openapi.json (OpenAPI 3.1)