Vision API Integration Guide

The Vision API is implemented by camera and vision integration partners on their own infrastructure. Hauler Hero calls the partner's endpoints to request, list, and download truck-camera video — both on-demand clips tied to specific stops or work orders, and continuous recordings covering full routes.

Prerequisites

You'll build and host this API on your own infrastructure, then share the URL and credentials with Hauler Hero.

A public URL reachable from the internet, subject to appropriate security controls.
An API-KEY that you issue to Hauler Hero. See Authentication.

Endpoints

Three endpoints across two workflows:

Endpoint	Workflow	Purpose
`POST /video-hero/v1/videos/requests`	On-demand	Initiate video preparation for a specific clip
`GET /video-hero/v1/videos`	On-demand	List available (prepared) videos — used to poll request status
`GET /video-hero/v1/videos/continuous`	Continuous	List continuous recordings for a truck over a time range

On-demand video workflow

Used when Hauler Hero needs a specific clip — for example, video tied to a stop or a work order.

Hauler Hero calls POST /video-hero/v1/videos/requests with customerId, truckId, cameraId, startTime, and endTime.
Your system begins discovery and preparation, returning 202 Accepted with a requestId and status: processing.
Hauler Hero polls GET /video-hero/v1/videos?requestId={requestId} to check whether the video is ready.
Once prepared, your response lists the video with a temporary downloadUrl and an expiresAt timestamp.
Hauler Hero downloads the file before the URL expires.

Continuous video workflow

Used when a customer needs the full-route recording — continuous video chunked into constant time durations.

Hauler Hero calls GET /video-hero/v1/videos/continuous with customerId, truckId, startTime, and endTime.
Your system returns a paginated list of recording chunks, each with its own temporary downloadUrl and expiresAt.
Hauler Hero downloads the recordings before the URLs expire.

Implementation requirements

Your implementation must:

Be reachable from the internet on a public IP, with appropriate security controls.
Authenticate requests via the API-KEY header.
Support precise video source specification — customer, truck, and (where applicable) camera.
Accept time ranges in ISO 8601 format.
Return temporary download URLs with an expiresAt giving Hauler Hero ample time to fetch the file.
Paginate list responses (page, pageSize, plus totalItems / totalPages in the response).

Request parameters

`POST /video-hero/v1/videos/requests`

Field	Required	Notes
`customerId`	Yes	Customer identifier
`truckId`	Yes	Truck identifier — ideally the same ID used for work-order and routing specification
`cameraId`	Yes	Camera identifier. Use placement names (`front`, `rear`, `left`, `right`) or a numbering scheme (`1`, `2`, `3`) — Hauler Hero accepts either
`startTime`	Yes	ISO 8601 timestamp
`endTime`	Yes	ISO 8601 timestamp

`GET /video-hero/v1/videos`

Parameter	In	Required	Notes
`customerId`	query	Yes	Customer identifier
`truckId`	query	No	Filter by truck
`cameraId`	query	No	Filter by camera
`requestId`	query	No	Filter by a specific video request — used for polling a single request's status
`startTime`	query	No	ISO 8601 lower bound
`endTime`	query	No	ISO 8601 upper bound
`page`	query	No	Default `1`
`pageSize`	query	No	Default `20`, max `100`

`GET /video-hero/v1/videos/continuous`

Parameter	In	Required	Notes
`customerId`	query	Yes	Customer identifier
`truckId`	query	Yes	Truck identifier
`cameraId`	query	No	Filter by camera
`startTime`	query	Yes	ISO 8601 start of range
`endTime`	query	Yes	ISO 8601 end of range
`page`	query	No	Default `1`
`pageSize`	query	No	Default `20`, max `100`

See the Schemas section of the Vision API reference for the exact response shapes.

Response codes

Shared across all three endpoints:

Code	Error code	Meaning	When your implementation should return this
`200` / `202`	—	Success	`202` for accepted video requests, `200` for list endpoints
`400`	`INVALID_PAYLOAD`	Invalid parameters	Required field missing or malformed (e.g., `startTime` after `endTime`)
`401`	`UNAUTHORIZED`	API key invalid or missing	`API-KEY` header is missing or doesn't match what you issued
`404`	`NOT_FOUND`	Customer, truck, or camera not found	No matching entity in your system
`500`	`INTERNAL_ERROR`	Unexpected error	Log the incident for your own investigation

Download URLs

Download URLs are temporary — give Hauler Hero ample time to fetch the file and include an expiresAt timestamp on every URL so the caller knows how long it's valid.

Support

Integration questions: integrations@haulerhero.com
API support: api-support@haulerhero.com