REST APIs

Event List and Event Details

Welcome!

The Smarter AI Platform is an enablement software platform for AI cameras that see, listen, and understand.

The Smarter AI Platform is comprised of:

  • cameras / camera libraries
  • cloud servers / services
  • mobile viewer apps / libraries

The Smarter AI platform supports event triggers based on any combination of:

  • inferencing jobs and workflows
  • sensor data
  • telematics data

This guide will show you how to integrate event lists and event metadata into your web applications via Smarter AI server/service REST APIs.

Step 1. Getting Ready

1.1. Here is what's needed to begin:

  • Tenant Name → Your tenant is your private working space for users, cameras, events, & more.
  • API Key → The key to access your tenant through Smarter AI REST APIs.

Please contact [email protected], if you're missing your Tenant Name or an API Key.

1.2. Please ensure that your cameras are up to date with the latest camera software.

Step 2. Get the list of Events

In this section, we'll be discussing:

  • How to get the list of cameras?
  • How to get the list of Events for a specific camera or all cameras in your tenant?

2.1. Retrieve the list of all cameras in your tenant. This list will provide the camera ID number for each camera.
This API has several parameters:

  • type - Endpoint type:
    • APP - Mobile application client.
    • DEVICE - A dashcam, a gateway, etc.
  • status - Device or app status.
    • ACTIVE - A device (camera) is onboarded and operational.
    • RESET - A device (camera) has been removed from a tenant.
curl --request GET \
     --url https://api.smarterai.com/v4/endpoints?type=device&status=active \
     --header 'Accept: application/json' \
     --header 'SAI-Key: YOUR_API_KEY'

[
  {
    "userId": [USERID],
    "status": "ACTIVE",
    "id": [ENDPOINTID],
    "type": "DEVICE"
  },
  
...

  {
    "userId": [USERID],
    "status": "ACTIVE",
    "id": [ENDPOINTID],
    "type": "DEVICE"
  }
]

2.2. Get event count.

curl --head \
     --url https://api.smarterai.com/v4/events \
     --header 'Accept: application/json' \
     --header 'SAI-Key: YOUR_API_KEY'

HTTP/1.1 200 
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Total-Count: 131
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Set-Cookie: JSESSIONID=D458E0E3F96F5326C8805DB13C79A7DD; Path=/; Secure; HttpOnly
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 05 Aug 2022 11:11:10 GMT

In our example, the X-Total-Count value is 131.

2.3. Get an Event List for a device (camera). You can set the following parameters as well:

  • endpointId
  • trigger
  • startTime & endTime (define the time range)
curl --request GET \
     --url https://api.smarterai.com/v4/events?endpointId=[ENDPOINTID]&startTime=1658217600000&endTime=1658476800000 \
     --header 'Accept: application/json' \
     --header 'SAI-Key: YOUR_API_KEY'

[
  {
    "id": "818690217686328",
    "endpointId": [ENDPOINTID],
    "timestamp": 1659705818041,
    "triggerId": "b63ad4e0-ebb3-456c-9649-0c3d8c463965",
    "triggerName": "My Trigger",
    "deviceLabel": "CAM01020000",
    "snapshot1": "SNAPSHOT_URL1",
    "snapshot2": "SNAPSHOT_URL2"
  },

...

  {
    "id": "818667314111082",
    "endpointId": [ENDPOINTID],
    "timestamp": 1659703526909,
    "triggerId": "b63ad4e0-ebb3-456c-9649-0c3d8c463965",
    "triggerName": "My Trigger",
    "deviceLabel": "CAM01020002",
    "snapshot1": "SNAPSHOT_URL1",
    "snapshot2": "SNAPSHOT_URL2"
  },
]

Here are the key parts of the API response:

  • triggerName
  • timestamp
  • endpointId
  • snapshot1 → Road Camera Snapshot.
  • snapshot2 → Cabin Camera Snapshot.
  • snapshot3 → Rear Camera Snapshot. (optional)

2.4. Get an Event List for all devices (cameras). 

# Array with device IDs (continue array if needed)
endpointIDs=("0000", "0001", ...)
for item in "${endpointIDs[@]}"
do
  url='https://api.smarterai.com/v4/events?endpointId='$item'&startTime=1658217600000&endTime=1658476800000'
  curl --request GET \
     --url $url \
     --header 'Accept: application/json' \
     --header 'SAI-Key: YOUR_API_KEY'

  # Process results
  # ...
done

Here is what is provided by the script above:

  1. Events Count
  2. Video Snapshots
  3. Device Name
  4. Trigger Name

Step 3. Event Details

Get access to an event's snapshots and metadata.

3.1. The following request provides event metadata such as:

  • event start and end timestamp
  • event name
  • device name
  • endpoint id
curl --request GET \
     --url https://api.smarterai.com/v4/events/804774584580474 \
     --header 'Accept: application/json' \
     --header 'SAI-Key: YOUR_API_KEY'

{
  "id": "804774584580474",
  "tenantId": "[TENANTID]",
  "endpointId": "[ENDPOINTID]",
  "deviceId": "CAM01020002",
  "startTimestamp": 1658314255636,
  "endTimestamp": null,
  "triggerId": "2693baea-e4a8-495b-a39f-309f277f5e6d",
  "triggerName": "Right Turn",
  "deviceLabel": "John Doe's Car Camera",
  "userInitiatedEventRequestId": null,
  "snapshots": [
    {
      "source": "vid_2",
      "downloadUrl": "https://download.smarterai.com/abc",
      "downloadUrlExpirationTime": 1735343697935
    },
    {
      "source": "vid_1",
      "downloadUrl": "https://download.smarterai.com/lmn",
      "downloadUrlExpirationTime": 1735343697935
    },
    {
      "source": "sensor",
      "downloadUrl": "https://download.smarterai.com/xyz",
      "downloadUrlExpirationTime": 1735343697935
    }
  ]
}

The API response also includes:

  • Snapshot URLs - snapshots of all imagers.
  • Data array items with "source: sensor" and "type: DATA" contains sensor data, including:
    • Geolocation

To show the event player you can refer to this page.