Events

Introduction

Access Token

Access tokens are the secret passwords that gives access to your resources through the APIs. You can create an API token from the Cloud as described in the introduction.
Make sure to keep your tokens secret and to not publish them publicly to prevent any security breach.

API in use

The Cloud API centralizes all your teams, workspaces, devices, applications, logs and telemetries. hub.stereolabs.com/api/v1

List and query events

List events stored in the specified workspace identified by workspaceId. Multiple parameters are available to customize the output of this endpoint.

:workspaceId integer

Id of the target workspace.

fields string_list

optional Event's fields that should be returned by the request. This can be used to reduce amount of data retrieved by only selecting the needed fields. ?fields=timestamp,label,payload

Available fields: id, device_id, timestamp, duration, payload, retention, tags, label, application_name, deployment_id, reference, notes
Payload fields: A field can also be taken from the payload with the following notation ?fields=payload.temperature,payload.humidity

ids integer_list

optional Filter the events from their Id. ?ids=125,356,542

devices integer_list

optional Filter events based on the devices that emitted them. ?devices=1,5

labels string_list

optional Filter events based on their label. ?labels=detections,environment

tags string_list

optional Only select events matching all the tags listed. ?tags=main_building

start
end timestamp

optional Only select the events published within the specified the time-range. ?start=1567413071229&end=1567419371229
start and end can be used independently. Timestamps can be provided in the following formats:

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp.
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string. (must be url-encoded)

application_names string_list

optional Only select events produced by applications matching the listed names (url-encoded). ?application_names=webserver,people counter

deployment_ids integer_list

optional Only select events produced by applications instances matching the listed deployment ids. ?deployment_ids=434445,684650

sort
sort_direction field_list
string_list

optional Sort the returned events by the specified key. ?sort=timestamp&sort_direction=DESC
The order can be specified with the sort_direction parameter that can be DESC or ASC whether you are using descending or ascending sorting. If more than one key is given, the next fields will be used when sorting with the previous key reported an equality. ?sort=label,payload.humidity&sort_direction=ASC,DESC

filter_op
filter_field
filter_value string
field
value

optional Filter out events that doesn't match the specified condition. ?filter_field=payload.temperature&filter_op=gt&filter_value=30
Only return events with a reported temperature over 30° (where temperature is a custom field in the payload).
Available filter operations are:

gt: is greater than
gte: is greater than or equal
lt: is lower than
lte: is lower than of equal
eq: is equal
neq: is different
contains: is containing the value (string)

To avoid type ambiguity when filtering on a payload key, use the filter_value_type parameter and set it to number or string.
To use more than one filter, append from _1 to _10 at the end of each filter_* parameter. ?filter_field_2=payload.humidity&filter_op_2=eq&filter_value_2=95

agg
agg_field
agg_step string
field
timestamp

optional This parameter will change the output format by returning aggregates of events in time-intervals rather than a event list.
?agg=mean&agg_field=payload.temperature&start=1567413071229&end=1567419371229
Returns the average temperature in a time-range (where payload.temperature is a custom field)
Available aggregations are:

count: Count the number of events matching the provided parameters
sum: Sum of the values found in the queried events for the agg_field
avg: Average of the values found in the queried events for the agg_field
min: Minimum value found in the queried events for the agg_field
max: Maximum value found in the queried events for the agg_field

If an agg_step is provided, result will be split in multiple time ranges, starting from start and incrementing by agg_step up to the end.
An additional agg_identifier can be used to split result in groups based on key's value.
?agg=count&agg_identifier=device_id&start=1567413071229&end=1567419371229&agg_step=36000000
Count the number of events reported by each device in 10 minutes intervals.

per_page
page
after integer
integer_or_field
value

optional Controls the pagination of the returned events list. ?per_page=25
By default, the events's timestamp is used to sort the returned page, providing the latest events first.

Keyset pagination By using page to select the sorting key, and after to specify the position of the page, pagination will return per_page events starting right after after value. ?per_page=25&page=timestamp&after=1567413071229
Offset pagination By using page as a number, pagination will return per_page events starting from the most recent one. ?per_page=25&page=1

limit
offset integer
integer

optional Skip some events (offset) and limits the number of events returned by the request. ?offset=50&limit=25

events array

List of events matching the specified parameters.

/workspaces/:workspaceId/events

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/events \
  -G  \
  -d 'labels=intrusion' \
  -d 'tags=main_building' \
  -d 'fields=id,device_id,timestamp,duration,payload' \
  -d 'start=1580201472695' \
  -d 'filter_field=duration' \
  -d 'filter_op=gt' \
  -d 'filter_value=1000'

HTTP/1.1 200 OK
{
  "events": [
    {
      "id": "343536",
      "device_id": "67890",
      "duration": "5000",
      "timestamp": "1580205472695",
      "payload": {
         "people_count": 3
      }
    },
    ...
  ]
}

Publish event

Publish a new event from the specified device.

:workspaceId integer

Id of the target workspace.

:deviceNameOrId integer

Id or url-encoded name of the associated device.

label string

A string representing the type of event sent. This field is later used during data consultation to filter relevant events.

tags string_list

optional A comma-separated list of tag to associate with the event. Tags could be used in queries to filter specific events.

payload object

The actual event data in a json format.

timestamp timestamp

optional The time at which the event has been generated. Default value is the timestamp at which the request is sent.
Timestamp can be provided in the following formats:

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string (must be url-encoded)

duration number

optional The duration of the event in milliseconds.

retention number

optional The retention time of this event in days. If not set, the default value of 1 month (30 days) will be used.

application_name string

optional The name of the application sending the event message. This can be used to identify the application at the origin of the event.

deployment_id integer

optional The deployment id of the application instance sending the event message. This can be used to identify a specific installation and version of an application.

reference
reference_to string
string

optional Can be used to associate event to a parent one. reference and reference_to CANNOT be used at the same time.

reference: a unique string used as a root reference for yet-to-publish events
reference_to: the reference string used in a previously-published event

id integer

ID of the created event.

/workspaces/:workspaceId/devices/:deviceNameOrId/events

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/events \
  -d '{ 
  "timestamp": 1567416071229,
  "duration": 5000,
  "label": "intrusion",
  "tags": "main_building,south_entrance",
  "payload": {
    "people_count": 3
  }
}'

HTTP/1.1 200 OK
{
  "id": "313233"
}

Delete events

Delete events matching the parameters.

:workspaceId integer

Id of the target workspace.

ids integer_list

optional Filter the events from their Id. ?ids=125,356,542

devices integer_list

optional Filter events based on the devices that emitted them. ?devices=1,5

labels string_list

optional Filter events based on their label. ?labels=detections,environment

tags string_list

optional Only select events matching all the tags listed. ?tags=main_building

application_names string_list

optional Only targets events produced by applications matching the listed names (url-encoded). ?application_names=webserver,people counter

deployment_ids integer_list

optional Only targets events produced by applications instances matching the listed deployment ids. ?deployment_ids=434445,684650

start
end timestamp

optional Only target the events published within the specified the time-range. ?start=1567413071229&end=1567419371229
start and end can be used independently. Timestamps can be provided in the following formats:

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string (must be url-encoded)

/workspaces/:workspaceId/events

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X DELETE \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/events \
  -G  \
  -d 'labels=intrusion' \
  -d 'tags=main_building,south_entrance' \
  -d 'start=1580201472695' \
  -d 'end=1580312563849'

HTTP/1.1 200 OK
{}