Retrieve file link

Retrieve the link to an event file generated by the device. The URL remains active for approximately several minutes to a few hours. If this call is made shortly after the event, the event media may not be uploaded yet and a 404 error is returned. In this case, try again a few minutes later.
If multiple events are generated with the same timestamp, to the second, and the same media type, the media file from the last request is used for all of them. To have different media files for each virtual event, use timestamps that differ by at least a second.

This API can be used in two ways:

1. For events in a given period of time. The files can then be downloaded. All the information required for this call is available in the event object received from the GET /devices/{imei}/events call

2. For virtual events, without using the GET /devices/{imei}/events call. You need additional information, such as the virtual event configuration on your device and the IDs of the cameras connected to the device

Note: For video events, you may retrieve either a video or a snapshot. The snapshot will be taken from the middle of the event video.

To retrieve a concealed snapshot, the conceal service must be enabled, and either a regular snapshot, or a concealed video, must already be ready.

The snapshot will be taken from the middle of the event video.

If a video is not ready yet, requesting a snapshot should return this error message: "Snapshot cannot be retrieved as the event video is not ready yet. Please try again in two minutes."

If a concealed snapshot is requested, fetch it only if a concealed video, or a regular snapshot, is already available on S3. Otherwise, you will receive an informative error message: "Failed to retrieve a concealed snapshot. If Concealment is enabled, request a snapshot or a concealed video first."

Any snapshot events will still return a 404 error when requested with fileType=video.

This will work for all video events.

Request

Security:

bearerAuth

path Parameters

imei

required

string (IMEI)

The IMEI of the device. The IMEI number can be found on a sticker on the device itself or on the back of the device box.

Example: 357660101000198

query Parameters

fileId	string (File ID) Filter by the ID of the requested file. Obtain this from the /devices/{imei}/events call or calculate the unix timestamp (seconds from epoch) of the event (applicable only to virtual events). Example: fileId=1595077872
fileType	string (File type) Filter by the file type of the requested file. Obtain this from the /devices/{imei}/events call or set to the value of video/snapshot if the device configuration is predefined. Enum: "video" "snapshot"
cameraId	string Filter by the ID of the in-cab or road-facing lens, or any paired auxiliary camera for the requested file. Obtain this from the /devices/{imei}/events call or set to the ID of the desired view if the configuration of the device is predefined: 1 - road-facing lens, 2 - in-cab lens, 50+ - auxiliary cameras. Use 0 for all cameras, or with the cameraIds parameter for a list of specific cameras. Example: cameraId=1
cameraIds	string A list of the camera IDs, separated by a comma. This may include the in-cab or road-facing lens, or any paired auxiliary camera: 1 - road-facing lens, 2 - in-cab lens, 50+ - auxiliary cameras. The list of cameras can be used only if cameraId=0 is provided. Example: cameraIds=1,2,51,52
conceal	boolean When set to true, retrieves a link to a version of an event media file with faces or license plates blurred. This parameter is optional. It is available for integrations in Europe. Example: conceal=true
eventId	integer (Event ID) Event ID in query Example: eventId=3

Responses

200

Successful operation

400

Bad request error

401

Unauthorized error

403

Forbidden error

404

Not found error

429

Too many requests error - try again later

500

Internal server error

get/devices/{imei}/event-file-link

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-prod.surfsight.net/v2/devices/:imei/event-file-link?fileId=1595077872&fileType=video&cameraId=1&cameraIds=1%2C2%2C51%2C52&conceal=true&eventId=3' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Response samples

application/json

{"data": {"url": "https://sample.s3.aws.com/123/123.mp4?access_key=1234"
}
}