Introduction

The Sighthound Data API is a REST API that is used to extract meta-data from Sighthound devices. The API is separated into several different namespaces, which provide access to different datasets. Those sections are the following:

Data - This is a legacy namespace that provides access to raw data and ad-hoc aggregations of raw data. Sighthound Analytics output will not be available via this namespace.

Stream - This is the next generation of the data namespace. This namespace provides access to both row level data and ad-hoc aggregations of data. The row level data available in the stream namespace provides a detailed view of the event in the meta field of the response. The meta field provides the entire Sighthound analytics output, which can be found here

Roll Up - Provides access to streaming data aggregations & the ability to configure streaming aggregations. Roll-ups allow you to pre-configure aggregations amongst multiple streams, devices, and sensors. For example if you want to know the count of vehicles in a parking lot via sensors drawn on two different streams, you can create a roll-up that will calculate the number of vehicles in the parking lot via sensors at each of the entrance and exit points.

Device Status - Provides access to device status data.

Service Account - Provides access to configure service accounts for access to data APIs.

Alerts (Beta) - Provides access to configure alerts.

Authentication

Sighthound uses API keys to allow access to the API. You can register a new Sighthound API Key at our Integrations Portal.

Sighthound expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-API-KEY: 38ed7729792c48489945c8060255fa45

Event Values

Event values & direction differ depending on the sensor type. The following details provide information as to what you can expect from the value and direction field of the common sensor types.

Sensor Type	Value	Direction
COUNT	The # of objects that crossed a given line	NORTH/SOUTH - based on the direction of the crossing.
SPEED	The estimated speed of an object between two lines.	NORTH/SOUTH - based on the direction of the crossing of the two lines.
FISH	The estimated length of a fish.	NORTH/SOUTH - based on the exit direction of the fish.
PRESENCE	The amount of time (in seconds) that an object spent in a region of interest. If the value is reported as 0for a presence sensor, there is currently an object in the region of interest.	N/A
COLLISION	The amount of time (in seconds) that the objects spent in a region of interest at the same time	N/A

Datatypes

Timestamps

All data APIs utilize ISO DateTimeFormat. This allows you to specify the timezone in the request of the API. The following are examples of valid timestamp formats for the API

"2021-06-01T00:00.000Z"
"2021-06-01T00:00.000+06:00"
"2021-06-01T00:00.000-06:00"
"2021-03-08T20:00.000+1100"

Sensor Data / Meta

Presence Sensor

The presence sensor is used to determine the number of objects within a give region of interest.

{
  "active" : true,
  "numObjectsInRegion" : 2,
  "object" : {
    "enteredOn" : 1624247455819,
    "objectType" : "person",
    "uniqueId" : 7953144757666971748
  },
  "startOn" : 1624247455553
}

{
  "active" : false,
  "numObjectsInRegion" : 0,
  "object" : {
    "enteredOn" : 1624247516781,
    "exitOn" : 1624247522937,
    "objectType" : "person",
    "uniqueId" : 6472069442200142026
  },
  "startOn" : 1624247516781,
  "stopOn" : 1624247522937,
  "timeOn" : 6.1558170318603516
}

Field	Description	Type	Default Value	Examples
active	Whether or not there is currently an object actively in the region of interest.	boolean	false	true false
numObjectsInRegion	The number of objects that are in the region of interest at the time of the associated event.	integer	2	2 5
object	The object which triggered the presence sensor.	object		`{"enteredOn":1624247455819,"objectType":"person","uniqueId":7953144757666971748}`
startOn	The time for which the presence sensor was first active. Measured in number of milliseconds from epoch.	integer		1624247455553
stopOn	The time for which the presence sensor became inactive. Measured in number of milliseconds from epoch.	integer		1624247522937
timeOn	The amount of time, in seconds that the region of interest was occupied. This field is only populated once the region of interest is no longer active.	double		6.155817031860352

Data

Query Aggregated Sensor Data

api_key="38ed7729792c48489945c8060255fa45"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"



curl "https://data-api.boulderai.com/data/query?startTime=${startTime}&endTime=${endTime}" \
  -d '{"deviceId":"BAI_0000111","streamId":null,"sensors":["COUNT_PERSON_1","SPEED_CAR_1"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","interval":"1 hour","functions":["COUNT","SUM","AVERAGE","MIN","MAX","MEDIAN","QUARTILE_1","QUARTILE_2","QUARTILE_3"],"fillEmptyWindows":true,"order":"ASCENDING"}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

[
  {
    "deviceId" : "BAI_0000111",
    "sensorName" : "COUNT_PERSON_1",
    "direction" : "NORTH",
    "windowStart" : "2021-01-15T00:00:00.000Z",
    "windowEnd" : "2021-01-15T01:00:00.000Z",
    "values" : [
      {
        "function" : "COUNT",
        "value" : 10.0
      },
      {
        "function" : "SUM",
        "value" : 10.0
      },
      {
        "function" : "AVERAGE",
        "value" : 10.0
      },
      {
        "function" : "MIN",
        "value" : 10.0
      },
      {
        "function" : "MAX",
        "value" : 10.0
      },
      {
        "function" : "MEDIAN",
        "value" : 10.0
      },
      {
        "function" : "QUARTILE_1",
        "value" : 10.0
      },
      {
        "function" : "QUARTILE_2",
        "value" : 10.0
      },
      {
        "function" : "QUARTILE_3",
        "value" : 10.0
      }
    ]
  }
]

This endpoint is used to query sensor data over a specific time period with aggregation methods.

Function	Description
COUNT	Count of occurrences
SUM	Sum of all values
AVERAGE	Average of all values
MIN	Minimum value
MAX	Maximum value
MEDIAN	Median value
QUARTILE_1	Value at the 1st quartile
QUARTILE_2	Value at the 2nd quartile
QUARTILE_3	Value at the 3rd quartile

HTTP Request

POST /data/query?startTime={startTime}&endTime={endTime}

Query Parameters

Parameter	Required	Description	Example
startTime	true	The startTime of the report to generate.	2021-01-15T00:00:00.000Z
endTime	true	The endTime of the report to generate.	2021-01-15T04:00:00.000Z

Query Flattened Sensor Data

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/data/sensor/query" \
  -d '{"deviceId":"BAI_0000111","sensors":["COUNT_PERSON_1","SPEED_CAR_1"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","withImages":true,"withTracks":false,"limit":10,"order":"DESCENDING"}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

[
  {
    "id" : "e7992846-85e4-434d-87c2-31ef3892990d",
    "deviceId" : "BAI_0000111",
    "objectType" : "person",
    "sensorName" : "COUNT_PERSON_1",
    "direction" : "SOUTH",
    "timeCollected" : "2021-01-15T00:01:00.000Z",
    "value" : 1.0,
    "boundingBoxImage" : null,
    "frameImage" : null,
    "track" : null
  },
  {
    "id" : "e5ff3d8f-0df5-40d3-974f-7f0d0e32e02e",
    "deviceId" : "BAI_0000111",
    "objectType" : "car",
    "sensorName" : "SPEED_CAR_1",
    "direction" : "NORTH",
    "timeCollected" : "2021-01-15T00:02:00.000Z",
    "value" : 45.0,
    "boundingBoxImage" : null,
    "frameImage" : null,
    "track" : null
  }
]

This endpoint is used to query sensor data over a specific time period.

HTTP Request

POST /data/sensor/query

Get Sensor Data by Id

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/data/id/${workspaceId}/${eventId}" \
  -X GET \
  -H "X-API-KEY: $api_key"

[
  {
    "deviceId" : "BAI_0000111",
    "objectType" : "person",
    "timeCollected" : "2021-01-15T00:00:00.000Z",
    "uniqueId" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
    "confidence" : 0,
    "model" : "peoplecounter_V0.1",
    "length" : null,
    "speed" : null,
    "sensorData" : {
      "sensorName" : "COUNT_PERSON_3",
      "objectClass" : "person",
      "direction" : 1
    },
    "track" : null,
    "bboxImg" : null,
    "frameImg" : null
  }
]

This endpoint is used to retrieve a specific event on a device.

HTTP Request

GET /data/id/{workspaceId}/{eventId}

Get Sensors by Device

api_key="38ed7729792c48489945c8060255fa45"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"



curl "https://data-api.boulderai.com/device/${deviceId}/sensors?startTime=${startTime}&endTime=${endTime}" \
  -X GET \
  -H "X-API-KEY: $api_key"

[
  {
    "deviceId" : "BAI_0000111",
    "streamId" : null,
    "sensorName" : "COUNT_PERSON_1",
    "direction" : "NORTH",
    "objectType" : "person",
    "count" : 10,
    "lastTimeCollected" : "2021-01-15T04:00:00.000Z"
  },
  {
    "deviceId" : "BAI_0000111",
    "streamId" : null,
    "sensorName" : "SPEED_CAR_1",
    "direction" : "SOUTH",
    "objectType" : "car",
    "count" : 10,
    "lastTimeCollected" : "2021-01-15T04:00:00.000Z"
  }
]

This endpoint is used to get a list of sensors that exist over a specific time period.

HTTP Request

GET /device/{deviceId}/sensors?startTime={startTime}&endTime={endTime}

Query Parameters

Parameter	Required	Description	Example
startTime	true	The startTime of the report to generate.	2021-01-15T00:00:00.000Z
endTime	true	The endTime of the report to generate.	2021-01-15T04:00:00.000Z

Get Sensors by Workspace

api_key="38ed7729792c48489945c8060255fa45"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"



curl "https://data-api.boulderai.com/workspace/${workspaceId}/sensors?startTime=${startTime}&endTime=${endTime}" \
  -X GET \
  -H "X-API-KEY: $api_key"

[
  {
    "deviceId" : "BAI_0000111",
    "streamId" : null,
    "sensorName" : "COUNT_PERSON_1",
    "direction" : "NORTH",
    "objectType" : "person",
    "count" : 10,
    "lastTimeCollected" : "2021-01-15T04:00:00.000Z"
  },
  {
    "deviceId" : "BAI_0000111",
    "streamId" : null,
    "sensorName" : "SPEED_CAR_1",
    "direction" : "SOUTH",
    "objectType" : "car",
    "count" : 10,
    "lastTimeCollected" : "2021-01-15T04:00:00.000Z"
  }
]

This endpoint is used to get all of the sensors that have reported data for a given workspace over a period of time.

HTTP Request

GET /workspace/{workspaceId}/sensors?startTime={startTime}&endTime={endTime}

Query Parameters

Parameter	Required	Description	Example
startTime	true	The startTime of the report to generate.	2021-01-15T00:00:00.000Z
endTime	true	The endTime of the report to generate.	2021-01-15T04:00:00.000Z

Media

The media endpoints are used to query media data that is extracted from sensors. The response will reference a url which is reference to a storage location (Google Cloud Storage, Amazon S3, etc.). In order to request permissions to access the given media for your workspace please reach out to Sighthound support.

Get Latest Media Data

api_key="38ed7729792c48489945c8060255fa45"
mediaType="IMAGE"



curl "https://data-api.boulderai.com/media/${streamId}/latest?mediaType=${mediaType}" \
  -X GET \
  -H "X-API-KEY: $api_key"

[
  {
    "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
    "streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
    "id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
    "deviceId" : "BAI_0000111",
    "timeCollected" : "2021-01-15T00:00:00.000Z",
    "mediaType" : "IMAGE",
    "url" : "gs://**/**/7fe553c8-cc34-11ea-9439-0242ac120002-bb-frame.jpg",
    "captureType" : "RAW",
    "startTime" : null,
    "durationMs" : null,
    "objects" : [
    ],
    "events" : [
    ]
  }
]

This endpoint is used to retrieve the latest media from a stream.

HTTP Request

GET /media/{streamId}/latest?mediaType={mediaType}

Query Parameters

Parameter	Required	Description	Example
mediaType	false	The mediaType which you want to query	IMAGE

Query Media Data

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/media/query" \
  -d '{"streamId":"11c33a12-5098-450a-9fc3-cf9d97b958a7","mediaType":"IMAGE_AND_VIDEO","startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z"}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

[
  {
    "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
    "streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
    "id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
    "deviceId" : "BAI_0000111",
    "timeCollected" : "2021-01-15T00:00:00.000Z",
    "mediaType" : "VIDEO",
    "url" : "gs://**/**/7fe553c8-cc34-11ea-9439-0242ac120002-input-video.mp4",
    "captureType" : "RAW",
    "startTime" : "2021-01-15T00:00:00.000Z",
    "durationMs" : 10000,
    "objects" : [
      {
        "objectId" : 7953144757666971748
      }
    ],
    "events" : [
      {
        "eventId" : "aeb624a3-7a47-48d9-8530-72b233f5ad96"
      }
    ]
  },
  {
    "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
    "streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
    "id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
    "deviceId" : "BAI_0000111",
    "timeCollected" : "2021-01-15T00:00:00.000Z",
    "mediaType" : "IMAGE",
    "url" : "gs://**/**/7fe553c8-cc34-11ea-9439-0242ac120002-bb-frame.jpg",
    "captureType" : "RAW",
    "startTime" : null,
    "durationMs" : null,
    "objects" : [
    ],
    "events" : [
    ]
  }
]

This endpoint is used to query media from streams. Currently the API supports both image and video types.

HTTP Request

POST /media/query

Get Media Image or Video

api_key="38ed7729792c48489945c8060255fa45"
mediaId="aeb624a3-7a47-48d9-8530-72b233f5ad96"



curl "https://data-api.boulderai.com/media/${streamId}?mediaId=${mediaId}" \
  -X GET \
  -H "X-API-KEY: $api_key"

"No example provided."

This endpoint is used to retrieve a given media object.

HTTP Request

GET /media/{streamId}?mediaId={mediaId}

Query Parameters

Parameter	Required	Description	Example
mediaId	false	The mediaId which you want to query	aeb624a3-7a47-48d9-8530-72b233f5ad96

Stream

Get Latest Stream Data

api_key="38ed7729792c48489945c8060255fa45"
sensorId="185fda6c-f1a7-4149-9057-b8751a23be1b"



curl "https://data-api.boulderai.com/data/stream/${streamId}/latest?sensorId=${sensorId}" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
  "id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
  "sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
  "deviceId" : null,
  "direction" : "NORTH",
  "objectType" : "CAR",
  "timeCollected" : "2021-01-15T00:00:00.000Z",
  "value" : 10.0,
  "meta" : {
    "frameImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-frame.jpg",
    "boundingBoxImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-object.jpg"
  }
}

This endpoint is used to retrieve the latest data from a given stream.

HTTP Request

GET /data/stream/{streamId}/latest?sensorId={sensorId}

Query Parameters

Parameter	Required	Description	Example
sensorId	false	The sensor ID for which you want to query	185fda6c-f1a7-4149-9057-b8751a23be1b

Query Aggregated Stream Data

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/data/stream/aggregate/query" \
  -d '{"streamId":"11c33a12-5098-450a-9fc3-cf9d97b958a7","deviceId":null,"sensors":["185fda6c-f1a7-4149-9057-b8751a23be1b"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","interval":"1 hour","functions":["COUNT","SUM","AVERAGE","MIN","MAX","MEDIAN","QUARTILE_1","QUARTILE_2","QUARTILE_3"],"fillEmptyWindows":true,"order":"DESCENDING"}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

[
  {
    "streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
    "deviceId" : null,
    "sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
    "direction" : "NORTH",
    "windowStart" : "2021-01-15T00:00:00.000Z",
    "windowEnd" : "2021-01-15T04:00:00.000Z",
    "values" : [
      {
        "function" : "COUNT",
        "value" : 5.0
      },
      {
        "function" : "SUM",
        "value" : 5.0
      },
      {
        "function" : "AVERAGE",
        "value" : 5.0
      },
      {
        "function" : "MIN",
        "value" : 5.0
      },
      {
        "function" : "MAX",
        "value" : 5.0
      },
      {
        "function" : "MEDIAN",
        "value" : 5.0
      },
      {
        "function" : "QUARTILE_1",
        "value" : 5.0
      },
      {
        "function" : "QUARTILE_2",
        "value" : 5.0
      },
      {
        "function" : "QUARTILE_3",
        "value" : 5.0
      }
    ]
  }
]

This endpoint is used to query aggregated data by stream.

startTime & endTime are optional. If endTime is not defined, it will default to the current timestamp. If startTime is not defined, it will default to a single window aggregation between the endTime with a length of interval.

Function	Description
COUNT	Count of occurrences
SUM	Sum of all values
AVERAGE	Average of all values
MIN	Minimum value
MAX	Maximum value
MEDIAN	Median value
QUARTILE_1	Value at the 1st quartile
QUARTILE_2	Value at the 2nd quartile
QUARTILE_3	Value at the 3rd quartile

HTTP Request

POST /data/stream/aggregate/query

Query Flattened Sensor Data

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/data/sensor/query" \
  -d '{"deviceId":"BAI_0000111","sensors":["COUNT_PERSON_1","SPEED_CAR_1"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","withImages":true,"withTracks":false,"limit":10,"order":"DESCENDING"}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

[
  {
    "id" : "e7992846-85e4-434d-87c2-31ef3892990d",
    "deviceId" : "BAI_0000111",
    "objectType" : "person",
    "sensorName" : "COUNT_PERSON_1",
    "direction" : "SOUTH",
    "timeCollected" : "2021-01-15T00:01:00.000Z",
    "value" : 1.0,
    "boundingBoxImage" : null,
    "frameImage" : null,
    "track" : null
  },
  {
    "id" : "e5ff3d8f-0df5-40d3-974f-7f0d0e32e02e",
    "deviceId" : "BAI_0000111",
    "objectType" : "car",
    "sensorName" : "SPEED_CAR_1",
    "direction" : "NORTH",
    "timeCollected" : "2021-01-15T00:02:00.000Z",
    "value" : 45.0,
    "boundingBoxImage" : null,
    "frameImage" : null,
    "track" : null
  }
]

This endpoint is used to query sensor data over a specific time period.

HTTP Request

POST /data/sensor/query

Get Sensors by Workspace

api_key="38ed7729792c48489945c8060255fa45"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"



curl "https://data-api.boulderai.com/workspace/${workspaceId}/stream/sensor?startTime=${startTime}&endTime=${endTime}" \
  -X GET \
  -H "X-API-KEY: $api_key"

[
  {
    "streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
    "deviceId" : "BAI_0000111",
    "sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
    "sensorName" : "SPEED_CAR_1",
    "direction" : "NORTH"
  }
]

This endpoint is used to get all of the sensors that have reported data for a given workspace over a period of time.

HTTP Request

GET /workspace/{workspaceId}/stream/sensor?startTime={startTime}&endTime={endTime}

Query Parameters

Parameter	Required	Description	Example
startTime	true	The startTime of the report to generate.	2021-01-15T00:00:00.000Z
endTime	true	The endTime of the report to generate.	2021-01-15T04:00:00.000Z

Get Stream Data by Id

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/data/stream/${streamId}/event/${eventId}" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
  "id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
  "sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
  "deviceId" : null,
  "direction" : "NORTH",
  "objectType" : "CAR",
  "timeCollected" : "2021-01-15T00:00:00.000Z",
  "value" : 10.0,
  "meta" : {
    "frameImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-frame.jpg",
    "boundingBoxImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-object.jpg"
  }
}

This endpoint is used to query individual events by event id.

HTTP Request

GET /data/stream/{streamId}/event/{eventId}

Get Latest Stream Data

api_key="38ed7729792c48489945c8060255fa45"
sensorId="185fda6c-f1a7-4149-9057-b8751a23be1b"



curl "https://data-api.boulderai.com/data/stream/${streamId}/latest?sensorId=${sensorId}" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "streamId" : "11c33a12-5098-450a-9fc3-cf9d97b958a7",
  "id" : "aeb624a3-7a47-48d9-8530-72b233f5ad96",
  "sensorId" : "185fda6c-f1a7-4149-9057-b8751a23be1b",
  "deviceId" : null,
  "direction" : "NORTH",
  "objectType" : "CAR",
  "timeCollected" : "2021-01-15T00:00:00.000Z",
  "value" : 10.0,
  "meta" : {
    "frameImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-frame.jpg",
    "boundingBoxImage" : "https://storage.googleapis.com/demo_person_car_bicycle/gcpbai/BAI_0000111/2021-01-15/aeb624a3-7a47-48d9-8530-72b233f5ad96-object.jpg"
  }
}

This endpoint is used to retrieve the latest data from a given stream.

HTTP Request

GET /data/stream/{streamId}/latest?sensorId={sensorId}

Query Parameters

Parameter	Required	Description	Example
sensorId	false	The sensor ID for which you want to query	185fda6c-f1a7-4149-9057-b8751a23be1b

Query Flattened Sensor Data

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/data/sensor/query" \
  -d '{"deviceId":"BAI_0000111","sensors":["COUNT_PERSON_1","SPEED_CAR_1"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","withImages":true,"withTracks":false,"limit":10,"order":"DESCENDING"}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

[
  {
    "id" : "e7992846-85e4-434d-87c2-31ef3892990d",
    "deviceId" : "BAI_0000111",
    "objectType" : "person",
    "sensorName" : "COUNT_PERSON_1",
    "direction" : "SOUTH",
    "timeCollected" : "2021-01-15T00:01:00.000Z",
    "value" : 1.0,
    "boundingBoxImage" : null,
    "frameImage" : null,
    "track" : null
  },
  {
    "id" : "e5ff3d8f-0df5-40d3-974f-7f0d0e32e02e",
    "deviceId" : "BAI_0000111",
    "objectType" : "car",
    "sensorName" : "SPEED_CAR_1",
    "direction" : "NORTH",
    "timeCollected" : "2021-01-15T00:02:00.000Z",
    "value" : 45.0,
    "boundingBoxImage" : null,
    "frameImage" : null,
    "track" : null
  }
]

This endpoint is used to query sensor data over a specific time period.

HTTP Request

POST /data/sensor/query

Roll Up

Configure RollUp

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/aggregations/rollups" \
  -d '{"name":"My Roll-up","workspace":"04605210-c349-49ef-8c59-c1b986cddde3","ingress":[{"deviceId":"BAI_0000111","sensorName":"COUNT_PERSON_1","direction":"NORTH"}],"egress":[{"deviceId":"BAI_0000111","sensorName":"COUNT_PERSON_1","direction":"SOUTH"}],"parent":null,"initialValue":100,"minimumValue":10,"maximumValue":1000,"scheduledAdjustments":[{"expression":"0 15 10 ? * MON-FRI","adjustmentType":"SET_TO_VALUE","adjustmentValue":100},{"expression":"0 30 11 ? * *","adjustmentType":"STANDARD","adjustmentValue":10}],"meta":{"key":"value"}}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

{
  "id" : "91729333-5e01-4fe3-9a87-f43048a660ba",
  "name" : "My Roll-up",
  "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "ingress" : [
  ],
  "egress" : [
  ],
  "parent" : null,
  "initialValue" : 100,
  "minimumValue" : 10,
  "maximumValue" : 100,
  "scheduledAdjustments" : [
  ],
  "meta" : {
    "key" : "value"
  },
  "createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
  "createdAt" : "2022-04-06T14:25:04.565Z",
  "updatedBy" : null,
  "updatedAt" : null
}

This endpoint is used to configure roll-ups. Roll-ups are used in the occupancy management application.

HTTP Request

POST /aggregations/rollups

Get Roll Up Config

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/aggregations/rollups/config/${rollUpId}" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "id" : "91729333-5e01-4fe3-9a87-f43048a660ba",
  "name" : "My Roll-up",
  "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "ingress" : [
  ],
  "egress" : [
  ],
  "parent" : null,
  "initialValue" : 100,
  "minimumValue" : 10,
  "maximumValue" : 100,
  "scheduledAdjustments" : [
  ],
  "meta" : {
    "key" : "value"
  },
  "createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
  "createdAt" : "2022-04-06T14:25:04.565Z",
  "updatedBy" : null,
  "updatedAt" : null
}

Get the configuration for a specific roll up.

HTTP Request

GET /aggregations/rollups/config/{rollUpId}

Query Roll Up

api_key="38ed7729792c48489945c8060255fa45"
rollUpId="91729333-5e01-4fe3-9a87-f43048a660ba"
startTime="2021-01-15T00:00:00.000Z"
endTime="2021-01-15T04:00:00.000Z"



curl "https://data-api.boulderai.com/aggregations/rollup-query?rollUpId=${rollUpId}&startTime=${startTime}&endTime=${endTime}" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "data" : [
    {
      "rollUpId" : "91729333-5e01-4fe3-9a87-f43048a660ba",
      "startTime" : "2021-01-15T00:00:00.000Z",
      "endTime" : "2021-01-15T01:00:00.000Z",
      "value" : 100.0,
      "meta" : {
        "ingress" : 10.0,
        "egress" : 50.0,
        "adjustments" : 0.0
      }
    }
  ]
}

Query historical roll-up values for a given time range.

HTTP Request

GET /aggregations/rollup-query?rollUpId={rollUpId}&startTime={startTime}&endTime={endTime}

Query Parameters

Parameter	Required	Description	Example
rollUpId	true	The roll up ID for which you want to query	91729333-5e01-4fe3-9a87-f43048a660ba
startTime	true	The startTime of the report to generate.	2021-01-15T00:00:00.000Z
endTime	true	The endTime of the report to generate.	2021-01-15T04:00:00.000Z

Get Roll-Up Configurations

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/aggregations/rollups/workspace/${workspaceId}" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "rollups" : [
    {
      "id" : "91729333-5e01-4fe3-9a87-f43048a660ba",
      "name" : "My Roll-up",
      "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
      "currentValue" : 150,
      "lastUpdated" : "2021-01-15T04:00:00.000Z"
    }
  ]
}

This endpoint is used to retrieve the configured roll-ups for a given workspace.

HTTP Request

GET /aggregations/rollups/workspace/{workspaceId}

Delete a Roll-Up

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/aggregations/rollup/${rollUpId}" \
  -X DELETE \
  -H "X-API-KEY: $api_key"

{
  "success" : true
}

This endpoint is used to delete a specific roll-up.

HTTP Request

DELETE /aggregations/rollup/{rollUpId}

Get Roll-Up Details

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/aggregations/rollup/${rollUpId}/details" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "currentValue" : 100,
  "lastUpdated" : "2021-01-15T04:00:00.000Z",
  "specs" : [
    {
      "description" : "ingress",
      "value" : 50.0
    },
    {
      "description" : "egress",
      "value" : 100.0
    }
  ]
}

This endpoint is used to retrieve the details for a specific roll-up.

HTTP Request

GET /aggregations/rollup/{rollUpId}/details

Adjust Roll-Up Value

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/aggregations/rollup/${rollUpId}/value" \
  -d '{"workspaceId":"04605210-c349-49ef-8c59-c1b986cddde3","rollUpId":"91729333-5e01-4fe3-9a87-f43048a660ba","value":150}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

{
  "rollUpId" : "91729333-5e01-4fe3-9a87-f43048a660ba",
  "startTime" : "2021-01-15T00:00:00.000Z",
  "endTime" : "2021-01-15T01:00:00.000Z",
  "value" : 250.0,
  "meta" : {
    "ingress" : 10.0,
    "egress" : 20.0,
    "adjustments" : 250.0
  }
}

This endpoint is used to adjust a roll-up’s current value. This adjustment will add to the existing value.

HTTP Request

POST /aggregations/rollup/{rollUpId}/value

Service Account

Create Service Account

api_key="38ed7729792c48489945c8060255fa45"
workspaceId="04605210-c349-49ef-8c59-c1b986cddde3"



curl "https://data-api.boulderai.com/integrations/serviceAccount?workspaceId=${workspaceId}" \
  -d '{"workspace":"04605210-c349-49ef-8c59-c1b986cddde3","label":"My API Key","allowedOrigins":["https://platform.boulderai.com"],"isActive":true,"expiredAt":null}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

{
  "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "label" : "My API Key",
  "apiKey" : "38ed7729792c48489945c8060255fa45",
  "isActive" : true,
  "allowedOrigins" : [
    "https://platform.boulderai.com"
  ],
  "createdAt" : "2021-01-15T00:00:00.000Z",
  "lastUpdatedAt" : "2021-01-15T00:00:00.000Z",
  "expiredAt" : null,
  "createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
  "updatedBy" : null
}

This endpoint is used to create service accounts in a given workspace.

HTTP Request

POST /integrations/serviceAccount?workspaceId={workspaceId}

Query Parameters

Parameter	Required	Description	Example
workspaceId	true	The workspaceId which you want to query	04605210-c349-49ef-8c59-c1b986cddde3

Get Service Accounts

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/integrations/serviceAccount" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "serviceAccounts" : [
    {
      "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
      "label" : "My API Key",
      "apiKey" : "38ed7729792c48489945c8060255fa45",
      "isActive" : true,
      "allowedOrigins" : [
        "https://platform.boulderai.com"
      ],
      "createdAt" : "2021-01-15T00:00:00.000Z",
      "lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
      "expiredAt" : null,
      "createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
      "updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
    }
  ]
}

This endpoint is used to retrieve all of the service accounts for a given workspace.

HTTP Request

GET /integrations/serviceAccount

Delete Service Account

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/integrations/serviceAccount/${serviceAccountKey}" \
  -X DELETE \
  -H "X-API-KEY: $api_key"

{
  "success" : true
}

This endpoint is used to delete a service account.

HTTP Request

DELETE /integrations/serviceAccount/{serviceAccountKey}

Update Service Account

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/integrations/serviceAccount/${serviceAccountKey}" \
  -d '{"allowedOrigins":["https://google.com","https://amazon.com","https://microsoft.com"],"isActive":true,"expiredAt":"2021-01-15T04:00:00.000Z","label":"This is a new label."}' \
  -X PATCH \
  -H "X-API-KEY: $api_key"

{
  "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "label" : "This is a new label.",
  "apiKey" : "38ed7729792c48489945c8060255fa45",
  "isActive" : true,
  "allowedOrigins" : [
    "https://google.com",
    "https://amazon.com",
    "https://microsoft.com"
  ],
  "createdAt" : "2021-01-15T00:00:00.000Z",
  "lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
  "expiredAt" : "2021-01-15T04:00:00.000Z",
  "createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
  "updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
}

This endpoint is used to update a service account.

HTTP Request

PATCH /integrations/serviceAccount/{serviceAccountKey}

Alerts (Beta)

Alert Types

There are currently three different alert types are supported in the Sighthound platform:

Device Down - Triggered when a device has not transmitted a status in more than 5 minutes.
Device Restart - Triggered when a device is restarted. This is not necessarily a problem, unless a device is continuously restarting which could cause loss of data.
Lack of Data - This is an alert that is triggered when a given device or stream has not transmitted an event in a configured period of time.

Create Alert Configuration

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/alerts/config" \
  -d '{"workspaceId":"04605210-c349-49ef-8c59-c1b986cddde3","devices":["BAI_0000111"],"emails":["john.denver@boulderai.com"],"webhooks":null}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

{
  "id" : "b184dca3-e146-4453-9830-45bdad8ed410",
  "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "devices" : [
    "BAI_0000111"
  ],
  "emails" : [
    "john.denver@boulderai.com"
  ],
  "isActive" : true,
  "createdAt" : "2021-01-15T00:00:00.000Z",
  "lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
  "createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
  "updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
}

Configure device alerts for a list of devices.

HTTP Request

POST /alerts/config

Get Alert Configurations

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/alerts/config/${workspaceId}" \
  -X GET \
  -H "X-API-KEY: $api_key"

[
  {
    "id" : "b184dca3-e146-4453-9830-45bdad8ed410",
    "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
    "devices" : [
      "BAI_0000111"
    ],
    "emails" : [
      "john.denver@boulderai.com"
    ],
    "isActive" : true,
    "createdAt" : "2021-01-15T00:00:00.000Z",
    "lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
    "createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
    "updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
  }
]

Get all of the alert configs for a specific workspace

HTTP Request

GET /alerts/config/{workspaceId}

Delete a configured alert from the system.

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/alerts/config/${alertConfigId}" \
  -X DELETE \
  -H "X-API-KEY: $api_key"

{
  "success" : true
}

Delete Alert Configuration

HTTP Request

DELETE /alerts/config/{alertConfigId}

Update Alert Configuration

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/alerts/config/${alertConfigId}" \
  -d '{"devices":["BAI_0000111"],"emails":["john.denver@boulderai.com"],"isActive":true}' \
  -X PATCH \
  -H "X-API-KEY: $api_key"

{
  "id" : "b184dca3-e146-4453-9830-45bdad8ed410",
  "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "devices" : [
    "BAI_0000111"
  ],
  "emails" : [
    "john.denver@boulderai.com"
  ],
  "isActive" : true,
  "createdAt" : "2021-01-15T00:00:00.000Z",
  "lastUpdatedAt" : "2021-01-15T04:00:00.000Z",
  "createdBy" : "e519e625-7497-46ce-8e10-62f79735d474",
  "updatedBy" : "e519e625-7497-46ce-8e10-62f79735d474"
}

Update a specific alert configuration

HTTP Request

PATCH /alerts/config/{alertConfigId}

Create Alert Specification

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/alerts/specification" \
  -d '{"workspaceId":"04605210-c349-49ef-8c59-c1b986cddde3","alertType":"LackOfData","configuration":{"deviceId":"BAI_0000111","duration":"1 hour"}}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

{
  "id" : "705d9fec-a9db-4610-8d70-3cf558e5c866",
  "workspaceId" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "alertType" : "LackOfData",
  "configuration" : {
    "deviceId" : "BAI_0000111",
    "duration" : "1 hour"
  }
}

Create an alert specification

HTTP Request

POST /alerts/specification

Device Status

Get Latest Status

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/device/${deviceId}/status/latest" \
  -X GET \
  -H "X-API-KEY: $api_key"

{
  "deviceId" : "BAI_0000111",
  "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
  "localIp" : "68.9.240.254",
  "externalIp" : "241.201.188.52",
  "supervisorVersion" : "2.0.0",
  "sshRunning" : "False",
  "cpuUsage" : 50.0,
  "gpuUsage" : 75.0,
  "gpuTemp" : 37.5,
  "uptime" : {
    "days" : 10.0,
    "hours" : 12.0,
    "minutes" : 30.0,
    "seconds" : 5.0
  },
  "mainMemoryStorage" : {
    "totalSize" : 4.0,
    "inUse" : 3.0,
    "freeSpace" : 1.0,
    "percentageUse" : 75.0
  },
  "dataMemoryStorage" : {
    "totalSize" : 20.0,
    "inUse" : 10.0,
    "freeSpace" : 10.0,
    "percentageUse" : 50.0
  },
  "networkStatus" : [
    {
      "interface" : "eth0",
      "status" : "up",
      "dataRate" : {
        "daily" : {
          "upload" : {
            "bytes" : 10000,
            "errors" : 0,
            "dropped" : 0
          },
          "download" : {
            "bytes" : 10000,
            "errors" : 0,
            "dropped" : 0
          }
        },
        "monthly" : {
          "upload" : {
            "bytes" : 10000,
            "errors" : 0,
            "dropped" : 0
          },
          "download" : {
            "bytes" : 10000,
            "errors" : 0,
            "dropped" : 0
          }
        }
      }
    }
  ],
  "services" : [
    {
      "name" : "BAI_DataAcq_StandAlone_V4.0",
      "status" : {
        "bai_data_acq4" : "ADDED",
        "status" : "ADDED"
      }
    }
  ],
  "streams" : [
  ],
  "buildInfo" : {
    "assemblyVersion" : "0",
    "buildEnvironment" : {
      "basename" : "core-image-production",
      "machine" : "dnncam-v1-imx334",
      "l4tVersion" : "32.4.3",
      "distroVersion" : "2.10.0",
      "buildName" : "2.10.0-c3f4033-adam"
    },
    "assembly" : {
      "lens_motor_driver_use_sincere_imx334" : false,
      "node" : false,
      "4G" : false,
      "lens-resets-on-power-cycle" : false
    }
  },
  "lastSeen" : "2021-01-15T04:00:00.000Z"
}

This endpoint is used to retrieve the latest for a specific device.

HTTP Request

GET /device/{deviceId}/status/latest

Query Device Status

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/device/status/query" \
  -d '{"deviceId":"BAI_0000111","metrics":["cpuUsage","gpuUsage","gpuTemp"],"startTime":"2021-01-15T00:00:00.000Z","endTime":"2021-01-15T04:00:00.000Z","interval":"1 hour","order":"ASCENDING"}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-API-KEY: $api_key"

{
  "data" : [
    {
      "windowStart" : "2021-01-15T00:00:00.000Z",
      "metrics" : {
        "cpuUsage" : 50.0,
        "gpuUsage" : 50.0,
        "gpuTemp" : 50.0
      }
    }
  ]
}

This endpoint is used to query device status over a specified period of time.

The following are possible values for metrics:

Metric	Description
gpuUsage	Percentage of GPU Usage.
cpuUsage	Percentage of CPU Usage.
gpuTemp	Temperature of the GPU, in Celsius.
*	All possible metrics.

HTTP Request

POST /device/status/query

Get Latest Status by Workspace

api_key="38ed7729792c48489945c8060255fa45"




curl "https://data-api.boulderai.com/workspace/${workspaceId}/devices/status" \
  -X GET \
  -H "X-API-KEY: $api_key"

[
  {
    "deviceId" : "BAI_0000111",
    "workspace" : "04605210-c349-49ef-8c59-c1b986cddde3",
    "localIp" : "68.9.240.254",
    "externalIp" : "241.201.188.52",
    "supervisorVersion" : "2.0.0",
    "sshRunning" : "False",
    "cpuUsage" : 50.0,
    "gpuUsage" : 75.0,
    "gpuTemp" : 37.5,
    "uptime" : {
      "days" : 10.0,
      "hours" : 12.0,
      "minutes" : 30.0,
      "seconds" : 5.0
    },
    "mainMemoryStorage" : {
      "totalSize" : 4.0,
      "inUse" : 3.0,
      "freeSpace" : 1.0,
      "percentageUse" : 75.0
    },
    "dataMemoryStorage" : {
      "totalSize" : 20.0,
      "inUse" : 10.0,
      "freeSpace" : 10.0,
      "percentageUse" : 50.0
    },
    "networkStatus" : [
      {
        "interface" : "eth0",
        "status" : "up",
        "dataRate" : {
          "daily" : {
            "upload" : {
              "bytes" : 10000,
              "errors" : 0,
              "dropped" : 0
            },
            "download" : {
              "bytes" : 10000,
              "errors" : 0,
              "dropped" : 0
            }
          },
          "monthly" : {
            "upload" : {
              "bytes" : 10000,
              "errors" : 0,
              "dropped" : 0
            },
            "download" : {
              "bytes" : 10000,
              "errors" : 0,
              "dropped" : 0
            }
          }
        }
      }
    ],
    "services" : [
      {
        "name" : "BAI_DataAcq_StandAlone_V4.0",
        "status" : {
          "bai_data_acq4" : "ADDED",
          "status" : "ADDED"
        }
      }
    ],
    "streams" : [
    ],
    "buildInfo" : {
      "assemblyVersion" : "0",
      "buildEnvironment" : {
        "basename" : "core-image-production",
        "machine" : "dnncam-v1-imx334",
        "l4tVersion" : "32.4.3",
        "distroVersion" : "2.10.0",
        "buildName" : "2.10.0-c3f4033-adam"
      },
      "assembly" : {
        "lens_motor_driver_use_sincere_imx334" : false,
        "node" : false,
        "4G" : false,
        "lens-resets-on-power-cycle" : false
      }
    },
    "lastSeen" : "2021-01-15T04:00:00.000Z"
  }
]

This endpoint is used to retrieve the latest for all devices in a given workspace.

HTTP Request

GET /workspace/{workspaceId}/devices/status