> ## 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. # Inference completion callback (internal) > **Not part of the public API.** Called by the inference plane when a submitted unit of work settles. Authenticated by an HMAC-SHA256 of the raw body in `X-Modal-Signature`, keyed with a shared secret; unsigned or stale (> 5 min skew) calls are rejected with `401`. The callback is what closes the billing loop: `units_actual` is the real billable count (the per-detection meter is only knowable here), and the gateway commits that amount and releases the rest of the reservation in the same transaction. Deliveries are at-least-once and must be treated as idempotent on `(job_id, status)`. ## OpenAPI ````yaml /openapi.yaml post /internal/callbacks/modal 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: /internal/callbacks/modal: post: tags: - Internal summary: Inference completion callback (internal) description: > **Not part of the public API.** Called by the inference plane when a submitted unit of work settles. Authenticated by an HMAC-SHA256 of the raw body in `X-Modal-Signature`, keyed with a shared secret; unsigned or stale (> 5 min skew) calls are rejected with `401`. The callback is what closes the billing loop: `units_actual` is the real billable count (the per-detection meter is only knowable here), and the gateway commits that amount and releases the rest of the reservation in the same transaction. Deliveries are at-least-once and must be treated as idempotent on `(job_id, status)`. operationId: modalCallback parameters: - name: X-Modal-Signature in: header required: true description: '`t=,v1=.">`.' schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ModalCallback' responses: '204': description: Callback accepted. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' security: [] components: schemas: ModalCallback: type: object title: Modal completion callback description: >- Payload posted by the inference plane when a unit of work settles. Internal contract, not part of the public API surface. required: - job_id - status properties: job_id: $ref: '#/components/schemas/JobIdString' status: type: string description: Terminal state reached by the inference call. enum: - succeeded - failed output_ref: type: - string - 'null' description: >- Storage key of the serialised result written by the worker. Required when `status` is `succeeded`. examples: - s3://carhub-out/2026/08/16/job_3ZxK9pQr7TnW.json units_actual: type: - integer - 'null' minimum: 0 description: >- Billable units really consumed. Only the worker knows this for the per-detection meter; the gateway commits exactly this amount and releases the rest. model_version: type: - string - 'null' description: Build that produced the output, surfaced on the job. examples: - plate-reader@2026-08-01 error: description: Populated when `status` is `failed`. oneOf: - $ref: '#/components/schemas/JobError' - type: 'null' provider_job_id: type: - string - 'null' description: >- Identifier on the inference provider's side, for cross-system tracing. duration_ms: type: - integer - 'null' minimum: 0 description: Wall-clock time of the inference call, fed into latency metrics. 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 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 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' 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 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 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 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 headers: RequestId: description: Unique identifier of this request. Quote it in any support conversation. schema: type: string examples: - 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`. ````