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

Property	Description
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