Skip to main content
POST
Preview — Driver License Reader

Authorizations

Authorization
string
header
required

Organisation API key, sent as Authorization: Bearer chk_live_….

  • chk_live_… — real inference, real credits, livemode: true.
  • chk_test_… — identical pipeline against the fixture backend, test credits, livemode: false.

Keys are stored hashed; only the prefix (chk_live_a1b2…) is ever displayed again. A key may be scoped to a subset of endpoint families — calling outside its scopes is a 403.

Headers

Idempotency-Key
string

Client-generated key (a UUID is ideal) making this POST safe to retry. The first request is executed and its response stored for 24 h; any replay with the same key returns that stored response with Idempotent-Replayed: true and bills nothing. Reusing a key with a different payload is a 409 idempotency_key_reuse.

Required string length: 8 - 255
X-Carhub-Test-Scenario
string

Steers the fixture backend. Ignored by live keys, 400 test_scenario_not_supported if the scenario is unknown to the endpoint. Common catalogue:

Some endpoints add their own scenarios; unsupported common scenarios (for example empty_result on a generation endpoint) are rejected rather than silently ignored.

Examples:

"empty_result"

"low_confidence"

"model_error"

"slow"

"insufficient_credits"

Query Parameters

wait
boolean
default:false

Hold the connection until the job settles and answer 200 with the completed job instead of 202 with a queued one. Available on fast endpoints only; the ceiling is 30 s, after which the job keeps running and the call answers 202 as usual.

Body

images
file[]
required

Repeat in [front, back] order. JPEG, PNG, WebP or AVIF; 20 MB per image.

Required array length: 1 - 2 elements
country_hint
enum<string>

Supported issuing country. EU/EEA, United States and Canada only in v1.

Available options:
AT,
BE,
BG,
CA,
CY,
CZ,
DE,
DK,
EE,
ES,
FI,
FR,
GR,
HR,
HU,
IE,
IS,
IT,
LI,
LT,
LU,
LV,
MT,
NL,
NO,
PL,
PT,
RO,
SE,
SI,
SK,
US
Example:

"FR"

region_hint
string

ISO 3166-2 subdivision hint.

Pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$
Example:

"US-CA"

Response

Job completed synchronously (wait=true).

The unit of work of the API. Every inference call creates one, and every result is read back from one — synchronously through wait=true, or later through GET /v1/jobs/{id} or a webhook.

result is populated only in succeeded, error only in failed / expired.

id
string
required

Job identifier — job_ followed by a base58 string.

Pattern: ^job_[1-9A-HJ-NP-Za-km-z]{8,32}$
Example:

"job_3ZxK9pQr7TnW"

object
string
required
Allowed value: "job"
endpoint
enum<string>
required

Dotted slug of a CarHub endpoint, the identifier used for jobs and usage.

Available options:
vehicle.pose,
vehicle.segment,
vehicle.identify,
vin.read,
plate.read,
document.read,
dashboard.read,
engine.detect,
damage.detect,
damage.severity,
tire.read,
tire.detect,
parts.recognize,
parts.segment,
parts.decompose,
pricing.vehicle,
pricing.repair,
render.background,
render.enhance,
render.plate,
render.360,
render.video,
render.hotspots
status
enum<string>
required

Lifecycle of a job. queuedprocessing → one of succeeded | failed; expired when it was never picked up in time, canceled when it was cancelled before starting. The three settled states are terminal.

Available options:
queued,
processing,
succeeded,
failed,
expired,
canceled
livemode
boolean
required

false when the job was created with a chk_test_ key: fixture result, test credits.

created
integer<int64>
required

Epoch seconds, UTC.

Example:

1755300000

started_at
integer<int64> | null
required

When the job left the queue. Null while queued.

Example:

1755300000

completed_at
integer<int64> | null
required

When the job settled. Null until then.

Example:

1755300000

model_version
string | null
required

Exact model build that produced the result, as <model>@<release date>. Null until the job starts. Pin your regression tests to it.

Example:

"plate-reader@2026-08-27"

credits
object
required

Credit accounting for the job. One thousand credits equal one USD. reserved is held at admission and charged is the real cost after settlement; unused credits are released.

result
driver_license.read result · object | null
required

Endpoint-specific payload, null until the job succeeds. See each endpoint's 200 / 202 schema for its exact shape.

error
object | null
required

Populated when status is failed or expired, null otherwise.

test_scenario
string

The X-Carhub-Test-Scenario that produced this job. Present on test-mode jobs that were steered by one, absent otherwise — a live job never carries it.

Example:

"low_confidence"