Video Management System

This API is used to export Video Incidents from systems like Genetec in to ALO

In order to have access to the VMS endpoints you will need extra permissions associated with your API Authentication Key. Contact ALO for more information about obtaining this permission.

Multipart File Uploads

For large files (100+ MB )you will need to upload in chunks. This process involve multiple steps:

  • Signal to ALO that you need to start a multipart upload (Create Multipart Upload)

  • Make a request to ALO to get the signed urls for all the file parts (Get Upload Urls)

  • Upload the URLs directly to S3 using the upload urls

  • Signal to ALO the you completed uploading the files (Complete Multipart Upload) if you have successfully uploaded the files.

  • Signal to ALO to abort the process (Abort Multipart Upload) if you were unable to upload the videos.

Create Multipart Upload

This starts the process of upload multipart files

GET/vms/incidents/{incident_id}/create_multipart_upload?file_id={fileId}&filename={filename}

Path Parameters

Parameter

Description

incident_id

Id of the incident you are uploading files for

Query Parameters

Parameter

Description

file_id

Unique id of the file being uploaded

filename

Name of the file being uploaded

Example Request

https://api.alo.ai/v1/vms/incidents/8d1635ed-f747-427c-9b35-d83a08d08ab5/create_multipart_upload?file_id=abc1&filename=test.mov

Success Response

A successful get response will have an HTTP status of 200

Response Properties

PropertyDescription

s3_key

s3_key you need to provide in the Get Upload Urls request

upload_id

upload_id that you ned to provide in the Get Upload Urls request

Example Response

{
    "s3_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/1dda6e79-ee85-4f85-a5e5-5429a65307c3/8d1635ed-f747-427c-9b35-d83a08d08ab5/test.mov",
    "upload_id": "sW2iCVWSqEZjSao9zVEIAoKkvBXY0mLZUPnCZEUHSB.3pGyLoNQT2_mVMzM.KwU.s.knO.4Hu2MLGsAi5tUZcchoPtrfowe9ZLVLdtFZh4uqcoKKo98Xv6x1tc3JQWNQ"
}

Get Upload Urls

In order for you to upload video files and thumbnails you need to make a request to get a signed S3 upload url.

For small files (under 100 MB) you can upload the filed on 1 piece.

For larger files you will need to upload in chunks. See Multipart File Uploads

POST /vms/incidents/{incident_id}/upload_urls

Path Parameters

Parameter

Description

incident_id

Id of the incident you are uploading files for

Body Parameters

Parameter

Required

Default

Description

files

Yes

{}

Hash of file objects by file id

File Object Definition

Parameter

Required

Default

Description

part_count

Yes (If multipart upload)

The number of part involved in the multipart upload

s3_key

Yes (If multipart upload)

S3 key that you received when creating a multipart upload

upload_id

Yes (If multipart upload)

Upload id that you received when creating a multipart upload

filename

Yes (If not a multipart upload)

Name of the file you are uploading if its not a multipart upload

Example Payload

This is what a payload might look like if you need urls for a multipart video and its thumbnail

{
    "files": {
        "fileId1": {            
            "part_count": 3, 
            "s3_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.mov", 
            "upload_id": "RYol1AUyBSuv7IEz7aXuvz8TwHsyfxAH6IR9O_8RVJaZGcaW2P3i_b_q0XcY6r1SVNyKo4Uxw0DXEwYIEVB5sQ0BlY1iEDDrJrDPlgF4cHZzeJOyY7Erpswl7TUEQa1K"
            },
         "fileId2": {"filename": "myThumbnail.jpg"}
         }
}

Success Response

A successful get response will have an HTTP status of 200

Response Properties

Example Response

{
    "incident_id": "8d1635ed-f747-427c-9b35-d83a08d08ab5",
    "max_upload_size_mb": -1,
    "uploads": {
        "fileId1": {
            "s3_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.mov",
            "signed_urls": [
                "https://.../vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.mov?partNumber=1&uploadId=RYol1AUyBSuv7IEz7aXuvz8TwHsyfxAH6IR9O_8RVJaZGcaW2P3i_b_q0XcY6r1SVNyKo4Uxw0DXEwYIEVB5sQ0BlY1iEDDrJrDPlgF4cHZzeJOyY7Erpswl7TUEQa1K&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAQPM6APGZG4E7AS7S%2F20240304%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240304T193827Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=dede63b4e807952fb860fd805d00f3a2ad8a7fefc9a4555c24bd1efde3e3aade",
                "https://.../vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.mov?partNumber=2&uploadId=RYol1AUyBSuv7IEz7aXuvz8TwHsyfxAH6IR9O_8RVJaZGcaW2P3i_b_q0XcY6r1SVNyKo4Uxw0DXEwYIEVB5sQ0BlY1iEDDrJrDPlgF4cHZzeJOyY7Erpswl7TUEQa1K&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAQPM6APGZG4E7AS7S%2F20240304%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240304T193827Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=31ee977feb09db5d3cf22414c64796887ca7502008be7f4b73f83d3473ca2787",
                "https://.../vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.mov?partNumber=3&uploadId=RYol1AUyBSuv7IEz7aXuvz8TwHsyfxAH6IR9O_8RVJaZGcaW2P3i_b_q0XcY6r1SVNyKo4Uxw0DXEwYIEVB5sQ0BlY1iEDDrJrDPlgF4cHZzeJOyY7Erpswl7TUEQa1K&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAQPM6APGZG4E7AS7S%2F20240304%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240304T193827Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=f45fed45a2200eb05ac657df5d0edc1f0deaff75f956c35299a8a78f7aca44be"
            ]
        },
        "fileId2": {
            "s3_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/1dda6e79-ee85-4f85-a5e5-5429a65307c3/8d1635ed-f747-427c-9b35-d83a08d08ab5/myThumbnail.jpg",
            "signed_urls": "https://.../vms/08697d4a-dd01-457f-a4f7-823f0ab35814/1dda6e79-ee85-4f85-a5e5-5429a65307c3/8d1635ed-f747-427c-9b35-d83a08d08ab5/myThumbnail.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAQPM6APGZG4E7AS7S%2F20240304%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240304T193827Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Signature=f88a081c07f5b04ad67812429cd4464368dc184b94ec2069ff691017ee4c60a2"
        }
    }
}

Complete Multipart Upload

Call the endpoint after you have uploaded your multipart files

POST /vms/incidents/{incident_id}/complete_multipart_upload

Body Parameters

Parameter

Required

Default

Description

s3_key

Yes

s3_key that was acquired in the Create Multipart Upload request

upload_id

Yes

upload_id that was acquired in the Create Multipart Upload request

parts

Yes

Array of etag strings. Each part will have an etag returned when you upload the part. The etags must be ordered by part (the first string in the array must be the etag for the first file part)

Example Payload

{            
    "s3_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.mov", 
    "upload_id": "RYol1AUyBSuv7IEz7aXuvz8TwHsyfxAH6IR9O_8RVJaZGcaW2P3i_b_q0XcY6r1SVNyKo4Uxw0DXEwYIEVB5sQ0BlY1iEDDrJrDPlgF4cHZzeJOyY7Erpswl7TUEQa1K",
    "parts": ["b6e2499aae6e4d7794b7a8cc23216cec", "70a52b9815e0b2796a2d911f1d08eef3", "d3295896bbec7e52efc32ad256f48c9a"]
}

Success Response

A successful get response will have an HTTP status of 200

The body of the response will contain the s3_key and upload_id

Abort Multipart Upload

If you start a mutlipart upload and it fails you need to make a request to abort the process.

GET /vms/incidents/{incident_id}/abort_multipart_upload?s3_key={s3_key}&upload_id={upload_id}

Path Parameters

Parameter

Description

incident_id

Id of the incident you are uploading files for

Query Parameters

Parameter

Description

s3_key

s3_key you provided during Create Multipart Upload

upload_id

upload_id you provided during Create Multipart Upload

Example Request

https://api.alo.ai/v1/vms/incidents/8d1635ed-f747-427c-9b35-d83a08d08ab5/abort_multipart_upload?s3_key=test2.MP4&upload_id=Nuen6pGbsLisRzlYM2Khi1F7cpXOAp_Uiy7HtAJGx0MEEyVaLLmpzeilojbKBi.b3M73UuEr4CRppIE4bpElxhvLoHO2KKC9Y3FuM49EHsbJvL1DiNESNEeWGppKBwd2

Success Response

A successful get response will have an HTTP status of 200

The body of the response will contain the s3_key and upload_id

Get An Incident

Get information about an incident that has already been uploaded to ALO

GET /vms/incidents/{incident_id}

Path Parameters

Parameter

Description

incident_id

Id of the incident you are requesting information about

Success Response

A successful get response will have an HTTP status of 200

Response Properties

Example Response Body

{
    "vms_incident": {
        "id": "8d1635ed-f747-427c-9b35-d83a08d08ab6",
        "title": "Hey There!",
        "description": "Something else description",
        "incident_at": "2023-02-02T11:04:12.987Z",
        "created_at": "2024-02-02T11:04:41.030Z",
        "updated_at": "2024-02-02T12:01:19.643Z",
        "longitude": 0,
        "latitude": 0,
        "uploaded_videos": [
            {
                "id": "good-file-2",
                "started_at": "2024-02-02T11:49:22.000Z",
                "ended_at": "2024-02-02T11:51:32.000Z",
                "camera_name": "192.168.0.241 - Camera - 01a",
                "camera_description": "",
                "camera_longitude": 0,
                "camera_latitude": 0,
                "s3_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxxxxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.mov",
                "s3_thumbnail_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxxxxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.jpg"
            }
        ],
        "failed_videos": [
            {
                "id": "bad-file-2",
                "started_at": "2024-02-02T11:49:22.000Z",
                "ended_at": "2024-02-02T11:51:32.000Z",
                "camera_name": "192.168.0.241 - Camera - 01",
                "camera_description": "",
                "camera_longitude": 0,
                "camera_latitude": 0,
                "upload_errors": [
                    "G64 export failed with: No video available for the camera during the selected time period. Try exporting using a different time range.."
                ]
            }
        ]
    }
}

Create/Update Incident

PUT /vms/incidents/{incident_id}

Path Parameters

Parameter

Description

incident_id

Id of the incident you are creating or updating

Body Parameters

Parameter

Required

Default

Description

title

No

Incident title

description

No

Incident Description

created_at

No

Date/Time Incident was created in external system

updated_at

No

Date/Time Incident was created in external system

longitude

No

Longitude of the incident

latitude

No

Latitude of the incident

uploaded_videos

Yes

[]

Array of uploaded video objects

failed_videos

Yes

[]

Array of video objects that failed to be uploaded to ALO

Video Object Definition

Parameter

Required

Default

Description

id

Yes

Unique id of the video

started_at

No

Date/Time the video started at

ended_at

No

Date/Time video ended at

camera_name

No

Name of the camera the recorded the video

camera_description

No

Description of the camera the recorded the video

camera_longitude

No

Longitude of the camera the recorded the video

camera_latitude

No

Latitude of the camera the recorded the video

s3_key

Yes (if video was successfully uploaded)

S3 key for the video file that was uploaded to ALO

s3_thumbnail_key

No

S3 key for the thumbnail file that was uploaded to ALO

upload_errors

Yes (if the video failed to upload to ALO)

[]

Array of strings representing any error messages that were gathered in the upload process

Example Payload

{
  "vms_incident": {
    "title": "Hey There!!",
    "description": "Something else description",
    "created_at": "2024-02-02T11:04:41.03Z",
    "updated_at": "2024-02-02T12:01:19.643Z",
    "incident_at": "2023-02-02T11:04:12.987Z",
    "latitude": 0.0,
    "longitude": 0.0,
    "uploaded_videos": [
        {
            "id": "good-file-2",
            "started_at": "2024-02-02T11:49:22Z",
            "ended_at": "2024-02-02T11:51:32Z",
            "camera_id": "01000000-0001-babe-0007-48ea632b7f71",
            "camera_name": "192.168.0.241 - Camera - 01a",
            "camera_description": "",
            "camera_latitude": 0.0,
            "camera_longitude": 0.0,
            "s3_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.mov",
            "s3_thumbnail_key": "vms/08697d4a-dd01-457f-a4f7-823f0ab35814/xxxx/8d1635ed-f747-427c-9b35-d83a08d08ab5/abc1_test.jpg"
        }
    ],
    "failed_videos": [
        {
            "id": "bad-file-2",
            "started_at": "2024-02-02T11:49:22Z",
            "ended_at": "2024-02-02T11:51:32Z",
            "camera_id": "01000000-0001-babe-0007-48ea632b7f71",
            "camera_name": "192.168.0.241 - Camera - 01",
            "camera_description": "",
            "camera_latitude": 0.0,
            "camera_longitude": 0.0,
            "errors": [
                "G64 export failed with: No video available for the camera during the selected time period. Try exporting using a different time range.."
            ]
        }
    ]
  }
}

Success Response

A successful get response will have an HTTP status of 200/201

Response Properties

The payload in the response will be the same as seen when calling GET on an existing incident

Last updated

Logo

© Copyright 2024 ALO.ai, Inc. • All Rights Reserved