> ## Documentation Index > Fetch the complete documentation index at: https://docs.trycarhub.com/llms.txt > Use this file to discover all available pages before exploring further. # Video Onboarding > Tool to illustrate in real time the progress of the inspection of a vehicle. - Allows to guide the user in the use of the video. - Shows the user's progress through the vehicle estimation process. - Offers the possibility of obtaining an improved video thanks to AI. Upload the walkaround with `POST /v1/uploads`, then submit its reference here. The clip is indexed into the capture steps of a walkaround, each step resolving to its best usable frame — those frames are what the rest of the pipeline consumes. `wait=true` is not supported. ## OpenAPI ````yaml /openapi.yaml post /v1/video/onboard openapi: 3.1.0 info: title: CarHub API version: '2026-08-01' summary: >- Automotive AI as a service — 24 inference endpoints, one asynchronous contract. description: > CarHub exposes automotive computer-vision and pricing models as plain HTTP endpoints. Every model is priced and rate-limited on its own — nothing requires adopting the rest. ## Two API surfaces | Surface | Prefix | Authentication | |---|---|---| | Inference (the product) | `/v1/…` | API key — `Authorization: Bearer chk_live_…` / `chk_test_…` | | Management (the dashboard) | `/mgmt/v1/…` | Short-lived JWT — `Authorization: Bearer ` | ## Everything is a job Every inference endpoint is `POST` and **asynchronous by default**: it answers `202` with a [`Job`](#/components/schemas/Job) in status `queued`. Collect the result by polling `GET /v1/jobs/{id}` or by subscribing to the `job.succeeded` / `job.failed` webhooks. Fast endpoints additionally accept `?wait=true`, which holds the connection until the job settles (30 s ceiling) and answers `200` with the same `Job` object in status `succeeded`. Video, 360 and bundle endpoints reject `wait` with `400 wait_not_supported` — their work outlives any reasonable request timeout. ## Inputs Every endpoint accepts two request encodings for the same operation: * `multipart/form-data` — the binary directly in the request (`image`, `audio`, `video` or `images[]` depending on the endpoint). Simplest path, capped at 10 MB per file. * `application/json` — `{"input_ref": "upl_…"}` (or `input_refs` for multi-asset endpoints) referencing an upload created through `POST /v1/uploads`. Required for videos and batches. Endpoint parameters are identical in both encodings. ## Idempotency Send `Idempotency-Key` on any `POST`. A replayed key returns the original response and never bills twice; reusing a key with a different payload is a `409 idempotency_key_reuse`. ## Test mode Keys prefixed `chk_test_` run the entire pipeline — auth, rate limiting, job lifecycle, ledger, signed webhooks — against a fixture backend instead of a GPU. Test jobs carry `livemode: false` and draw on a separate, freely rechargeable test credit balance. Drive the fixture backend per request with `X-Carhub-Test-Scenario`. termsOfService: https://trycarhub.com/terms contact: name: CarHub API support url: https://docs.trycarhub.com email: api@trycarhub.com license: name: Proprietary identifier: LicenseRef-CarHub-Commercial servers: - url: https://api.trycarhub.com description: Production (EU) security: - ApiKeyAuth: [] tags: - name: A — Understand the vehicle description: >- Identity, attributes and a clean capture — everything downstream reads from here. - name: B — Damage & condition description: Find it, then grade it, so your own rules can act on the result. - name: C — Parts description: >- Turns "there is damage" into "there is damage on this component" — what makes every downstream estimate defensible. - name: D — Money description: Valuation and repair cost, computed from what was actually observed. - name: E — Image production description: >- Exposed as raw infrastructure, not a batch retouching service. Call it per asset, in your own pipeline. - name: Inspections description: The eight-stage bundle, billed as a single blended inspection. - name: Jobs description: Status, results and history of asynchronous work. - name: Uploads description: Presigned storage for videos and batches. - name: Management description: >- Organisation, API keys, usage, billing and outgoing webhooks. JWT authenticated. - name: Internal description: Inbound callbacks from the inference plane. Never called by customers. externalDocs: description: CarHub developer documentation url: https://docs.trycarhub.com paths: /v1/video/onboard: post: tags: - A — Understand the vehicle summary: Video Onboarding description: > Tool to illustrate in real time the progress of the inspection of a vehicle. - Allows to guide the user in the use of the video. - Shows the user's progress through the vehicle estimation process. - Offers the possibility of obtaining an improved video thanks to AI. Upload the walkaround with `POST /v1/uploads`, then submit its reference here. The clip is indexed into the capture steps of a walkaround, each step resolving to its best usable frame — those frames are what the rest of the pipeline consumes. `wait=true` is not supported. operationId: onboardVideo parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/TestScenario' requestBody: required: true content: multipart/form-data: schema: allOf: - $ref: '#/components/schemas/MultipartVideoInput' - $ref: '#/components/schemas/VideoOnboardParams' application/json: schema: allOf: - $ref: '#/components/schemas/JsonSingleInput' - $ref: '#/components/schemas/VideoOnboardParams' responses: '202': description: Job accepted, credits reserved, work queued. headers: Request-Id: $ref: '#/components/headers/RequestId' Location: $ref: '#/components/headers/JobLocation' Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/VideoOnboardJob' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: > 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`. schema: type: string minLength: 8 maxLength: 255 examples: uuid: value: 8b1f1c2e-9d3a-4a51-9f0c-1c9a2f6d7b44 TestScenario: name: X-Carhub-Test-Scenario in: header required: false description: > Steers the fixture backend. Ignored by live keys, `400 test_scenario_not_supported` if the scenario is unknown to the endpoint. Common catalogue: | Scenario | Effect | |---|---| | *(absent)* | Deterministic success — the endpoint's `default` fixture. | | `empty_result` | Success with nothing detected: empty lists, null readings. | | `low_confidence` | Success with every confidence below 0.5. | | `model_error` | Job settles `failed`; the reservation is released. | | `slow` | Completion after ~30 s — makes `wait=true` time out. | | `insufficient_credits` | `402` at admission, no job created. | Some endpoints add their own scenarios; unsupported common scenarios (for example `empty_result` on a generation endpoint) are rejected rather than silently ignored. schema: type: string examples: - empty_result - low_confidence - model_error - slow - insufficient_credits schemas: MultipartVideoInput: type: object required: - video properties: video: type: string format: binary description: >- MP4 or MOV, 10 MB maximum inline — walkarounds are almost always larger, so prefer `/v1/uploads` and the JSON encoding. VideoOnboardParams: type: object properties: steps: type: array description: Capture steps to look for. Defaults to the eight exterior angles. items: type: string enum: - front - front_left - left - rear_left - rear - rear_right - right - front_right - dashboard - interior_front - interior_rear - boot - engine_bay enhance: type: boolean default: false description: Also return a stabilised, colour-corrected version of the clip. JsonSingleInput: type: object required: - input_ref properties: input_ref: $ref: '#/components/schemas/UploadRef' VideoOnboardJob: allOf: - $ref: '#/components/schemas/Job' - type: object properties: result: oneOf: - $ref: '#/components/schemas/VideoOnboardResult' - type: 'null' UploadRef: type: string description: Reference returned by `POST /v1/uploads`. pattern: ^upl_[1-9A-HJ-NP-Za-km-z]{8,32}$ examples: - upl_7Qm2hV9tXbLd Job: type: object title: Job description: > 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`. `stages` is present on inspection jobs only. required: - id - object - endpoint - status - livemode - created - started_at - completed_at - model_version - credits - result - error properties: id: $ref: '#/components/schemas/JobIdString' object: type: string const: job endpoint: $ref: '#/components/schemas/EndpointSlug' status: $ref: '#/components/schemas/JobStatus' livemode: type: boolean description: >- `false` when the job was created with a `chk_test_` key: fixture result, test credits. created: $ref: '#/components/schemas/Timestamp' started_at: description: When the job left the queue. Null while `queued`. oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' completed_at: description: When the job settled. Null until then. oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' model_version: type: - string - 'null' description: >- Exact model build that produced the result, as `@`. Null until the job starts. Pin your regression tests to it. examples: - plate-reader@2026-08-01 credits: $ref: '#/components/schemas/JobCredits' result: description: >- Endpoint-specific payload, null until the job succeeds. See each endpoint's `200` / `202` schema for its exact shape. oneOf: - type: object - type: 'null' error: description: Populated when `status` is `failed` or `expired`, null otherwise. oneOf: - $ref: '#/components/schemas/JobError' - type: 'null' stages: type: array description: >- Per-stage progress. Present on `inspections` jobs only, absent everywhere else. items: $ref: '#/components/schemas/JobStage' test_scenario: type: string description: >- 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. examples: - low_confidence VideoOnboardResult: type: object title: video.onboard result description: >- A walkaround clip indexed into the capture steps of an inspection: which steps are covered, which are missing, and the single best frame for each — those frames are what every downstream model consumes. required: - complete - coverage_ratio - duration_s - frames_indexed - steps - missing_steps - guidance - enhanced_video properties: complete: type: boolean description: True when every requested step resolved to a usable frame. coverage_ratio: type: number minimum: 0 maximum: 1 description: Share of the requested steps that came back `captured`. duration_s: type: number minimum: 0 frames_indexed: type: integer minimum: 0 description: Frames extracted and scored from the clip. steps: type: array description: One entry per requested capture step, in walkaround order. items: $ref: '#/components/schemas/OnboardingStep' missing_steps: type: array description: >- Codes of the steps that came back `missing` or `unusable`, for a re-shoot prompt. items: type: string guidance: type: array description: >- Timestamped capture advice, the material for the on-screen coaching of a re-recording. items: $ref: '#/components/schemas/OnboardingGuidance' enhanced_video: description: >- Stabilised and colour-corrected clip. Null unless `enhance` was requested. oneOf: - $ref: '#/components/schemas/RenderedAsset' - type: 'null' ErrorResponse: type: object title: Error response description: >- The single error envelope of the API. Every non-2xx response on every route group has exactly this shape. required: - error additionalProperties: false properties: error: $ref: '#/components/schemas/Error' JobIdString: type: string description: Job identifier — `job_` followed by a base58 string. pattern: ^job_[1-9A-HJ-NP-Za-km-z]{8,32}$ examples: - job_3ZxK9pQr7TnW EndpointSlug: type: string description: >- Dotted slug of a CarHub endpoint, the identifier used for jobs and usage. enum: - vehicle.analyze - vehicle.segment - vehicle.identify - vin.read - plate.read - document.read - dashboard.read - engine.detect - video.onboard - 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 - viewer.hotspots - inspections JobStatus: type: string description: > Lifecycle of a job. `queued` → `processing` → 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. enum: - queued - processing - succeeded - failed - expired - canceled Timestamp: type: integer format: int64 description: Epoch seconds, UTC. examples: - 1755300000 JobCredits: type: object description: > Credit accounting for the job. One credit equals one USD cent. `reserved` is held at admission and `charged` is the real cost after settlement; unused credits are released. required: - reserved - charged properties: reserved: type: integer minimum: 0 examples: - 20 charged: type: - integer - 'null' minimum: 0 description: Null while the job is unsettled. examples: - 20 JobError: type: object description: Why a job settled in `failed` or `expired`. required: - type - code - message properties: type: type: string enum: - processing_error - invalid_request - internal code: type: string examples: - model_inference_failed - unreadable_input - upstream_timeout - job_expired message: type: string JobStage: type: object title: Inspection stage description: > One of the eight stages of an inspection. Each stage is a real child job running on the same queue and the same workers as a direct call, so `job_id` is readable on its own through `GET /v1/jobs/{id}` and carries that stage's full, endpoint-specific result. required: - stage - endpoint - name - status - started_at - completed_at - job_id - error properties: stage: type: integer minimum: 1 maximum: 8 description: Position in the pipeline, 1-based. endpoint: allOf: - $ref: '#/components/schemas/EndpointSlug' description: >- The endpoint this stage runs — the same one you could have called directly. name: type: string description: >- Stable name of the stage, independent of which endpoint currently implements it — branch on this rather than on `endpoint` if you want your UI to survive a pipeline change. enum: - onboard_walkaround - isolate_vehicle - decompose_parts - detect_damage - grade_severity - price_repair - render_listing - anchor_hotspots model: type: string description: Model backing this stage. examples: - video-onboarding - car-segmentation - damage-detection status: $ref: '#/components/schemas/JobStatus' started_at: oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' completed_at: oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' job_id: description: Child job that ran the stage. Null before the stage starts. oneOf: - $ref: '#/components/schemas/JobIdString' - type: 'null' error: oneOf: - $ref: '#/components/schemas/JobError' - type: 'null' result: description: >- The stage's own result, inlined once it has succeeded. Same shape as the result of the endpoint named in `endpoint`. Absent while the stage is unsettled. type: object skipped: type: boolean description: >- True when the stage was excluded by the request's `stages` parameter. default: false OnboardingStep: type: object required: - code - label - status - timestamp_s - frame - feedback properties: code: type: string enum: - front - front_left - left - rear_left - rear - rear_right - right - front_right - dashboard - interior_front - interior_rear - boot - engine_bay label: type: string examples: - Front three-quarter, left status: type: string description: >- `unusable` means the step was filmed but the best frame is too blurred, too dark or too far to feed a model. enum: - captured - missing - unusable timestamp_s: type: - number - 'null' minimum: 0 description: >- Position of the best frame in the clip. Null when the step is missing. frame: description: The extracted best frame. Null when the step is missing. oneOf: - $ref: '#/components/schemas/RenderedAsset' - type: 'null' feedback: type: - string - 'null' description: Why the step is not usable, when it is not. examples: - Vehicle partly out of frame — step back about two metres. OnboardingGuidance: type: object required: - timestamp_s - type - message properties: timestamp_s: type: number minimum: 0 type: type: string enum: - move_closer - move_back - slow_down - hold_steady - too_dark - too_bright - obstructed message: type: string RenderedAsset: type: object title: Rendered asset description: >- A file produced by a generation endpoint, served from a signed URL that expires. Download and re-host anything you intend to keep — the object is also subject to your organisation's storage TTL. required: - url - expires_at - format properties: url: type: string format: uri expires_at: $ref: '#/components/schemas/Timestamp' format: type: string enum: - jpg - png - webp - mp4 - webm width: type: - integer - 'null' minimum: 1 height: type: - integer - 'null' minimum: 1 bytes: type: - integer - 'null' minimum: 0 Error: type: object required: - type - code - message - param - doc_url - request_id properties: type: type: string description: >- Broad class of the failure — enough to branch on without matching codes. enum: - invalid_request - authentication - permission - rate_limit - insufficient_credits - not_found - conflict - processing_error - internal code: type: string description: >- Stable machine-readable identifier, narrower than `type`. New codes may appear; treat an unknown code as its `type`. examples: - missing_input - invalid_api_key - rate_limit_exceeded message: type: string description: >- English, human-readable, safe to log. Never localised, never for end users. param: type: - string - 'null' description: >- The offending field or header, when the failure can be attributed to one. doc_url: type: string format: uri description: Documentation page for this exact code. examples: - https://docs.trycarhub.com/errors/missing_input request_id: type: string description: >- Identifier of the failing request, mirrored in the `Request-Id` header. examples: - req_2Kd8xQmPvL4T headers: RequestId: description: Unique identifier of this request. Quote it in any support conversation. schema: type: string examples: - req_2Kd8xQmPvL4T JobLocation: description: Absolute URL of the created job. schema: type: string format: uri examples: - https://api.trycarhub.com/v1/jobs/job_3ZxK9pQr7TnW IdempotentReplayed: description: >- `true` when this response was replayed from a previous request carrying the same `Idempotency-Key`. Absent when the request was executed for real. schema: type: boolean RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 examples: - 12 RateLimitLimit: description: Requests allowed in the current window for this endpoint and plan. schema: type: integer examples: - 120 RateLimitRemaining: description: Requests left in the current window. schema: type: integer examples: - 0 RateLimitReset: description: Epoch second at which the current window resets. schema: type: integer examples: - 1755300060 responses: BadRequest: description: > Malformed or unusable request — bad JSON, missing or oversized file, unknown parameter, `wait=true` on an endpoint that does not support it. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingInput: summary: No input supplied value: error: type: invalid_request code: missing_input message: Provide either a multipart `image` field or an `input_ref`. param: image doc_url: https://docs.trycarhub.com/errors/missing_input request_id: req_2Kd8xQmPvL4T waitUnsupported: summary: wait=true on a long-running endpoint value: error: type: invalid_request code: wait_not_supported message: >- This endpoint is long-running; poll the job or use a webhook instead. param: wait doc_url: https://docs.trycarhub.com/errors/wait_not_supported request_id: req_2Kd8xQmPvL4T Unauthorized: description: Missing, malformed, revoked or expired credential. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidKey: value: error: type: authentication code: invalid_api_key message: The provided API key is invalid or has been revoked. param: null doc_url: https://docs.trycarhub.com/errors/invalid_api_key request_id: req_2Kd8xQmPvL4T InsufficientCredits: description: > The organisation's balance cannot cover the reservation for this call. Nothing was queued and nothing was charged. Top up with `POST /mgmt/v1/billing/checkout` — or, in test mode, `POST /mgmt/v1/billing/test-credits`. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: emptyCreditBalances: value: error: type: insufficient_credits code: insufficient_credits message: Credit balance is 3 minor units; this call reserves 8. param: null doc_url: https://docs.trycarhub.com/errors/insufficient_credits request_id: req_2Kd8xQmPvL4T Forbidden: description: >- Authenticated but not allowed: key scope excludes this endpoint family, role too low for a management route, or the resource belongs to another organisation. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: outOfScope: value: error: type: permission code: scope_not_granted message: This API key is not scoped for the `render` endpoint family. param: null doc_url: https://docs.trycarhub.com/errors/scope_not_granted request_id: req_2Kd8xQmPvL4T NotFound: description: No such resource, or it is not visible to this credential. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknownJob: value: error: type: not_found code: job_not_found message: No job with id `job_3ZxK9pQr7TnW`. param: id doc_url: https://docs.trycarhub.com/errors/job_not_found request_id: req_2Kd8xQmPvL4T Conflict: description: >- The request contradicts the current state — an idempotency key replayed with a different body, or an upload reference already consumed. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotencyReuse: value: error: type: conflict code: idempotency_key_reuse message: >- This Idempotency-Key was already used with a different request body. param: Idempotency-Key doc_url: https://docs.trycarhub.com/errors/idempotency_key_reuse request_id: req_2Kd8xQmPvL4T RateLimited: description: Too many requests for this endpoint and plan. Back off and retry. headers: Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: tooFast: value: error: type: rate_limit code: rate_limit_exceeded message: >- Rate limit of 120 requests per minute exceeded for `plate.read`. param: null doc_url: https://docs.trycarhub.com/errors/rate_limit_exceeded request_id: req_2Kd8xQmPvL4T InternalError: description: >- Something broke on our side. The request was not billed. Retry with the same `Idempotency-Key`; if it persists, quote `request_id`. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal: value: error: type: internal code: internal_error message: An unexpected error occurred. param: null doc_url: https://docs.trycarhub.com/errors/internal_error request_id: req_2Kd8xQmPvL4T securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: CarHub API key description: > 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`. ````