RoscoLive API v1.0

Request custom video from device

PUT/events/custom_clips

Send a request to a camera for video and/or snapshots for a selected date-time window. After the request is sent, it will be processed and the request will be sent to the camera to retrieve the requested media.

Allowed duration can be from 5 seconds to 1 hour between start_ts and end_ts. Requested event will upload a video of the requested duration along with a snapshot which is taken from the "center" of the request.

:::info[]
For durations > 5 minutes, the request will be broken up into as many 5-minute duration events as it can, then the remaining will be made into its own event.
:::

After a custom video request is submitted, the server will send the request to retrieve the media from the camera at the nearest opportunity. This event will be added to the event list for the company and can be retrieved using the returned event_id in the response.

User Role Permissions

The following table shows which user roles are allowed to send requests using this API endpoint.

User Role	Allowed
Partner
Partner View
Custom Partner	Requires permissions to be enabled
Fleet Manager
Group Manager
User
Custom User	Requires permissions to be enabled

Considerations

Here are some things to consider when implementing the custom video request API endpoint for your application.

It is important to note that the cameras record captured video locally to a MicroSD card and only send video when requested by the server. These video files are recorded in First-In-First-Out (FIFO) order and when the SD card reaches capacity, the camera will begin removing video files according to this logic. The lifetime of these files is highly dependant on camera recording settings and how often the camera operates inside the vehicle.

  By default, cameras ship with a 128 GiB MicroSD and assuming default settings are applied to camera, that gives approximately 70h of continuous recording before the SD card fills.

By default, when the camera is powered off it also disconnects completely from the server and is unreachable until the next power-on. When requests are sent to the camera when "offline", they are queued and will be sent the next time the camera powers on and connects.

  The setting "Wake-up / Sleep" mode can be enabled for a camera which will allow it to stay connected to the server, even when powered off. When a request is sent to a camera that is in a "Sleep" state, the camera will awake and then process the custom video request.

It is possible to receive event video for a shorter duration then expected when requesting video around boundaries when the camera was recording and not recording. If a time window overlaps one of these boundaries, the camera will grab and return whatever is available within the window. It is important to consider data usage when requesting a custom video from a camera, especially when it is a longer duration video. Unlike typical IoT data, video is much larger and can eat up a camera's data usage very quickly if video is requested too frequently.

Request

Body Params multipart/form-data

device_id

integer

required

Unique ID of device

>= 0

Example:

1234567890

start_ts

string <date-time>

required

Start date/time for the desired time period.
For duration
d = end_ts - start_ts
snapshot_only=false: 5 seconds <= d <= 1 hour
snapshot_only=true: 5 minutes <= d <= 1 hour

>= 14 characters<= 14 characters

Example:

20240112132100

end_ts

string <date-time>

required

End date/time for desired time period.

>= 14 characters<= 14 characters

Example:

20240112132130

custom_event_type

string

optional

Field for adding notes or comments for the event. These will appear in the Notes of the event in the RoscoLive Events page.

data

string <json>

optional

Field for adding a data object as stringified JSON to store a set of values for any additional metadata required.

Example:

{ "foo": "bar" }

event_display_type

string

optional

Field for adding a custom event type to display in the RoscoLive UI, otherwise the event will display "Custom Event"

Default:

Custom Event

Example:

My New Event

Request samples

Responses

Request Exists(200)

404 (device doesn't exist)(404)

Created(201)

Bad Request(400)

HTTP Code: 200

Content Type : JSONapplication/json