Skip to content
/
Request on-demand video

Vision API (1.11.0)

Introduction

The Hauler Hero system includes functionality to provide imagery of container pickup in the context of each relevant stop or work order. We have a lot of customer demand for this feature and, at a macro level, this is a unique time for automation technology in general, and the development of visual recognition features is well timed to benefit from these advances.

In order to unlock the tremendous new value of next-generation service levels and additional revenue opportunities for our customers, and to capitalize on this unique juncture with us, we request our camera management partners to provide a specific set of functionality in their video access API. The key functionality is listed below.

On-Demand Video API

Access

We require a video access API to be reachable from the Internet on a public IP, subject to proper security controls. It should be a well documented API that would accept requests from our cloud computing infrastructure.

Video Source Specification

It should be straight-forward to specify the source of the video precisely, namely:

  • The customer (by name or ID),
  • The specific truck, ideally specified via the same ID as used for work order and routing specification already,
  • The camera on that truck, if it has several cameras. We have flexibility to utilize commonly understood naming for camera placement, as well as a predefined numbering scheme.

Time Range Specification

We need to be able to provide a time range, specified as a start and an end timestamp (ISO format), for the video range to be requested for downloading. This would initiate the process of video discovery and preparation for the export.

Video Downloading

Once the video has been requested per specifications above, we would need a polling interface to check whether the video has been prepared and is available for downloading. This could be a request API endpoint that would return a (paginated) list of available videos, based on the filtering specifications above. Each element of this list would specify the video source and time range of the video, and provide a downloadable link to the video (which could be valid temporarily, while giving us ample time to download the video).

On-Demand Video Workflow

  1. Hauler Hero calls POST /video-hero/v1/videos/requests with customer, truck, camera, and time range
  2. Partner begins video discovery and preparation for export
  3. Hauler Hero polls GET /video-hero/v1/videos to check whether video is prepared and available
  4. Partner returns a paginated list of available videos with downloadable links
  5. Hauler Hero downloads the video files using the provided links

Continuous Video API

Some of our customers would benefit from a continuous video made available to them that would show the truck moving along the full length of its route. Our system would be able to receive the continuous recordings via an API that would yield a paginated list of all continuous recordings (chunked into constant time durations) available within a given source and time range specification. This API would follow a similar access authorization and security, as the on-demand variant of the API.

Continuous Video Workflow

  1. Hauler Hero calls GET /video-hero/v1/videos/continuous with source and time range filters
  2. Partner returns a paginated list of continuous recordings chunked into constant time durations
  3. Hauler Hero downloads the recordings using the provided links

Additional Information Available

Please reach out to integrations@haulerhero.com if you have any questions or would like additional clarification.

Authentication

All requests require an API-KEY header for authentication.

Download OpenAPI description
vision.json
vision.yaml
Languages
Servers
Mock server
https://docs.haulerhero.com/_mock/vision
Partner production server
https://api.yourcompany.com

On-Demand Video

Request and retrieve on-demand video clips for specific stops or work orders

Operations

Request on-demand video

Request

Initiates the process of video discovery and preparation for export. Specify the video source (customer, truck, camera) and a time range (start and end timestamps in ISO 8601 format) for the video to be requested.

Security
apiKey
Bodyapplication/jsonrequired
customerIdstringrequired

Unique identifier or name for the customer

Example: "123e4567-e89b-12d3-a456-426614174000"
truckIdstringrequired

Truck identifier, ideally the same ID used for work order and routing specification

Example: "truck-5201"
cameraIdstringrequired

Camera identifier on the truck. Can use commonly understood naming for camera placement (e.g., "front", "rear", "left", "right") or a predefined numbering scheme (e.g., "1", "2", "3").

Example: "front"
startTimestring(date-time)required

Start of the requested video time range in ISO 8601 format

Example: "2026-02-04T08:30:00Z"
endTimestring(date-time)required

End of the requested video time range in ISO 8601 format

Example: "2026-02-04T08:35:00Z"
curl -i -X POST \
  https://docs.haulerhero.com/_mock/vision/video-hero/v1/videos/requests \
  -H 'API-KEY: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "truckId": "truck-5201",
    "cameraId": "front",
    "startTime": "2026-02-04T08:30:00Z",
    "endTime": "2026-02-04T08:35:00Z"
  }'

Responses

Video request accepted and processing has begun

Bodyapplication/json
successbooleanrequired

Whether the request was accepted

Example: true
requestIdstringrequired

Unique identifier for the video request, used for polling status

Example: "req-abc123-def456"
statusstringrequired

Current status of the video request

Enum"processing""ready""failed"
Example: "processing"
messagestring

Human-readable status message

Example: "Video request accepted. Poll GET /video-hero/v1/videos to check availability."
Response
application/json
{
  "success": true,
  "requestId": "req-abc123-def456",
  "status": "processing",
  "message": "Video request accepted. Poll GET /video-hero/v1/videos to check availability."
}

List available videos

Request

Returns a paginated list of available videos based on filtering specifications. Use this endpoint to poll whether requested videos have been prepared and are available for downloading. Each element specifies the video source, time range, and provides a downloadable link (which may be valid temporarily).

Security
apiKey
Query
customerIdstringrequired

Unique identifier for the customer

Example: customerId=123e4567-e89b-12d3-a456-426614174000
truckIdstring

Filter by truck identifier

Example: truckId=truck-5201
cameraIdstring

Filter by camera identifier or placement name

Example: cameraId=front
requestIdstring

Filter by a specific video request ID

Example: requestId=req-abc123-def456
startTimestring(date-time)

Filter videos starting from this ISO 8601 timestamp

Example: startTime=2026-02-04T08:30:00Z
endTimestring(date-time)

Filter videos ending before this ISO 8601 timestamp

Example: endTime=2026-02-04T08:35:00Z
pageinteger>= 1

Page number for pagination

Default 1
Example: page=1
pageSizeinteger[ 1 .. 100 ]

Number of results per page

Default 20
Example: pageSize=20
curl -i -X GET \
  'https://docs.haulerhero.com/_mock/vision/video-hero/v1/videos?customerId=123e4567-e89b-12d3-a456-426614174000&truckId=truck-5201&cameraId=front&requestId=req-abc123-def456&startTime=2026-02-04T08%3A30%3A00Z&endTime=2026-02-04T08%3A35%3A00Z&page=1&pageSize=20' \
  -H 'API-KEY: YOUR_API_KEY_HERE'

Responses

Videos retrieved successfully

Bodyapplication/json
successbooleanrequired

Whether the request was successful

Example: true
dataobjectrequired
data.​videosArray of objects(Video)

List of available videos

data.​paginationobject(Pagination)
Response
application/json
{
  "success": true,
  "data": {
    "videos": [ … ],
    "pagination": { … }
  }
}

Continuous Video

Access continuous full-route video recordings

Operations