Test mode

Validate your integration with deterministic API scenarios.

Use a chk_test_ API key to validate your integration before you send live inference traffic. Test requests go to the same base URL, https://api.trycarhub.com, and follow the same authentication, idempotency, job, credit-reservation and webhook paths as live requests.

Test and live credit balances are separate. A test request returns livemode: false in its job. It never runs a production model or consumes live credits.

Select a scenario

Set X-Carhub-Test-Scenario on an inference request. Omit the header for the endpoint’s deterministic successful fixture.

Header value	Expected outcome
(omit header)	Successful job using the default fixture.
empty_result	Successful job with no detections or readings.
low_confidence	Successful job with confidence values below 0.5.
model_error	Job settles as failed; its credit reservation is released.
slow	Completion takes about 30 seconds; use it to verify polling and webhook handling.
insufficient_credits	Submission returns 402 insufficient_credits; no job is created.

Some scenarios are not meaningful for every endpoint. CarHub rejects an unsupported scenario with 400 test_scenario_not_supported rather than silently falling back to a default response.

Example

curl -sS -X POST "https://api.trycarhub.com/v1/plate/read" \
  -H "Authorization: Bearer $CARHUB_TEST_KEY" \
  -H "Idempotency-Key: 8b1f1c2e-9d3a-4a51-9f0c-1c9a2f6d7b44" \
  -H "X-Carhub-Test-Scenario: low_confidence" \
  -F "image=@plate.jpg"

Test both an immediate response and a queued job. Use slow to confirm that your client keeps polling or accepts the corresponding webhook after wait=true reaches its 30-second limit.

Use a new idempotency key for each distinct test case. Reuse the same key only when you are verifying retry behaviour for the same payload.