# Request on-demand video

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.

Endpoint: POST /video-hero/v1/videos/requests
Version: 1.11.0
Security: apiKey

## Request fields (application/json):

  - `customerId` (string, required)
    Unique identifier or name for the customer
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `truckId` (string, required)
    Truck identifier, ideally the same ID used for work order and routing specification
    Example: "truck-5201"

  - `cameraId` (string, required)
    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"

  - `startTime` (string, required)
    Start of the requested video time range in ISO 8601 format
    Example: "2026-02-04T08:30:00Z"

  - `endTime` (string, required)
    End of the requested video time range in ISO 8601 format
    Example: "2026-02-04T08:35:00Z"

## Response 202 fields (application/json):

  - `success` (boolean, required)
    Whether the request was accepted
    Example: true

  - `requestId` (string, required)
    Unique identifier for the video request, used for polling status
    Example: "req-abc123-def456"

  - `status` (string, required)
    Current status of the video request
    Enum: "processing", "ready", "failed"

  - `message` (string)
    Human-readable status message
    Example: "Video request accepted. Poll GET /video-hero/v1/videos to check availability."

## Response 400 fields (application/json):

  - `success` (boolean, required)
    Always false for errors

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "INVALID_PAYLOAD", "UNAUTHORIZED", "INTERNAL_ERROR", "NOT_FOUND"

  - `error.message` (string, required)
    Human-readable error message
    Example: "Missing required field: truckId"

  - `error.details` (object)
    Additional error details (optional)

## Response 401 fields (application/json):

  - `success` (boolean, required)
    Always false for errors

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "INVALID_PAYLOAD", "UNAUTHORIZED", "INTERNAL_ERROR", "NOT_FOUND"

  - `error.message` (string, required)
    Human-readable error message
    Example: "Missing required field: truckId"

  - `error.details` (object)
    Additional error details (optional)

## Response 404 fields (application/json):

  - `success` (boolean, required)
    Always false for errors

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "INVALID_PAYLOAD", "UNAUTHORIZED", "INTERNAL_ERROR", "NOT_FOUND"

  - `error.message` (string, required)
    Human-readable error message
    Example: "Missing required field: truckId"

  - `error.details` (object)
    Additional error details (optional)

## Response 500 fields (application/json):

  - `success` (boolean, required)
    Always false for errors

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "INVALID_PAYLOAD", "UNAUTHORIZED", "INTERNAL_ERROR", "NOT_FOUND"

  - `error.message` (string, required)
    Human-readable error message
    Example: "Missing required field: truckId"

  - `error.details` (object)
    Additional error details (optional)