Request custom video from device

PUT

https://fleet.roscolive.com/api/v1.0/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.

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.

Video Availability

Wake-up / Sleep mode

Foreshortened Event Video

Data Usage

Request Example

Shell

JavaScript

Java

Swift

curl --location --request PUT 'https://fleet.roscolive.com/api/v1.0/events/custom_clips' \
--form 'device_id="1234567890"' \
--form 'start_ts="20240112132100"' \
--form 'end_ts="20240112132130"' \
--form 'custom_event_type=""' \
--form 'data="{ \"foo\": \"bar\" }"' \
--form 'event_display_type="My New Event"'

Response Example

200 - Success

{
    "meta": {
        "code": 200
    },
    "response": {
        "request_id": 1908766,
        "warning": "request exists"
    },
    "result": "OK"
}

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

Responses

🟢200Request Exists

application/json

Body

Request custom video from device

User Role Permissions#

Considerations#

Request

Responses

User Role Permissions

Considerations