# Vision API ## 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](mailto:integrations@haulerhero.com) if you have any questions or would like additional clarification. ## Authentication All requests require an `API-KEY` header for authentication. Version: 1.11.0 ## Servers Partner production server ``` https://api.yourcompany.com ``` ## Security ### apiKey API key for authenticating requests. To obtain an API key: - Contact your account manager - Email: integrations@haulerhero.com Include in request header: `API-KEY: your_api_key_here` Type: apiKey In: header Name: API-KEY ## Download OpenAPI description [Vision API](https://docs.haulerhero.com/_bundle/vision.yaml) ## On-Demand Video Request and retrieve on-demand video clips for specific stops or work orders ### Request on-demand video - [POST /video-hero/v1/videos/requests](https://docs.haulerhero.com/vision/on-demand-video/requestvideo.md): 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. ### List available videos - [GET /video-hero/v1/videos](https://docs.haulerhero.com/vision/on-demand-video/listvideos.md): 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). ## Continuous Video Access continuous full-route video recordings ### List continuous recordings - [GET /video-hero/v1/videos/continuous](https://docs.haulerhero.com/vision/continuous-video/listcontinuousrecordings.md): Returns a paginated list of all continuous recordings available within a given source and time range. Recordings are chunked into constant time durations. This endpoint enables customers to access a continuous video showing the truck moving along the full length of its route.