Public Endpoints

Public endpoints can be used on public or private dashboard pages in order to access data from the IoT platform.

Instead of needing to be a logged in user or needing to be linked to a specific device, these endpoints will retrieve data from any user for anyone, so use with caution.

For more information about public pages, check out our Public Pages doc.

 

Create an event

This endpoint is very similar to the regular create event endpoint. However, some of the parameters are within the URL instead of in the request body. 

Summary

  • Endpoint: /api/v2/public/devices/{device_id}/data/{stream}
  • Method: POST
  • Required User Type: None, this works for anyone, even if they are not a user

Path Parameters

  • device_id - string of user you want to create event for
    • Required
  • stream - stream to send data to
    • Required

Body Parameters

  • event_data - data to send
    • Required
    • Type: dictionary
  • observed_at - event timestamp
    • Default: Now
    • Type: Date object or ISO-8601 date string

Response

A successful response will return an array containing the event's event_id.

 

Example

Request URL:

/api/v2/public/devices/accounts/data/licensee_accounts

Request Body

{
event_data: {"test": "test1234", "test2": 1}
}

Response Data

["12345678"]

 

Retrieve data by stream

This endpoint is very similar to the regular retrieval endpoint. However, some of the parameters are within the URL instead of in the request body. 

Summary

  • Endpoint: /api/v2/public/devices/{device_ids}/data_by_stream/{stream}
  • Method: GET
  • Required User Type: None, this works for anyone, even if they are not a user

Path Parameters

  • device_ids - string of user you want to query data from or comma-separated string of users you want to query data from (ie "device1,device2")
    • Required
  • stream - stream to query data from
    • Required

Body Parameters

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • limit - maximum number of events to query
    • Default: 1000
    • Type: int
  • since - query events that occurred no earlier than this time
    • Default: Beginning of time
    • Type: Date object or ISO-8601 date string
  • until - query events that occurred no later than this time
    • Default: Now
    • Type: Date object or ISO-8601 date string
  • sort_by - part of event to sort by, typically "observed_at"
    • Default: None
    • Type: string
    • Required with use of "sort_direction"
  • sort_direction - either "asc" or "desc"
    • Default: None
    • Type: string
    • Required with use of "sort_by"
  • rule - rules to limit included data in response by tag presence or equality
    • Default: None
    • Type: list of strings
    • You must surround string tag values with quotes, ie ['name = "test name"']
  • xrule - rules to exclude data from response by tag presence or equality
    • Default: None
    • Type: list of strings
    • You must surround string tag values with quotes, ie ['name = "test name"']
  • filters - filters to limit included data in response with more complexity than rules

Response

A successful response will return an array of objects.

Each of the objects represents a different user (specified by the "device_id" parameter) and contains a "data" tag which is an array of events matching the query. Each event has "event_id", "observed_at", and "event_data" tags.

 

Example

Request URL

/api/v2/public/devices/accounts/data_by_stream/licensee_accounts

Request Body

{
limit: 1,
since: new Date(Date.now - 1000), // 1 second ago
sort_by: "observed_at",
sort_direction: "desc", // last events first
rule: ['tenant_user = "t_123"', 'amount = 100'],
xrule: ['name'] // exclude events with name tag,
filters: JSON.stringify({'AND':[['licensee_accounts.faculty_string', "CONTAINS", "abc"], ["licensee_accounts.licensee", "CASE_INSENSITIVE_CONTAINS", "animal"]]})
}

Response Data

[{
"tag": "_full_event_",
"device_id": "accounts",
"data": [{
"event_id": "123",
"observed_at": "2020-01-07T01:06:31.484870+00:00",
"event_data": {
"tenant_user": "t_123",
"amount": 100,
"faculty_string": "abc123",
"licensee": "ANIMALS!"
}]
}]

 

Retrieve data by tag

This endpoint is very similar to the regular retrieval endpoint. However, some of the parameters are within the URL instead of in the request body. 

Summary

  • Endpoint: /api/v2/public/devices/{device_ids}/data_by_tag/{tags}
  • Method: GET
  • Required User Type: None, this works for anyone, even if they are not a user

Path Parameters

  • device_ids - API basic user you want to query data from or comma-separated list of users you want to query data from (ie "device1,device2")
    • Required
  • tags - tag to query or comma-separated list of tags to query
    • Required

Body Parameters

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • limit - maximum number of events to query
    • Default: 1000
    • Type: int
  • since - query events that occurred no earlier than this time
    • Default: Beginning of time
    • Type: Date object or ISO-8601 date string
  • until - query events that occurred no later than this time
    • Default: Now
    • Type: Date object or ISO-8601 date string
  • sort_by - part of event to sort by, typically "observed_at"
    • Default: None
    • Type: string
    • Required with use of "sort_direction"
  • sort_direction - either "asc" or "desc"
    • Default: None
    • Type: string
    • Required with use of "sort_by"
  • rule - rules to limit included data in response by tag presence or equality
    • Default: None
    • Type: list of strings
    • You must surround string tag values with quotes, ie ['name = "test name"']
  • xrule - rules to exclude data from response by tag presence or equality
    • Default: None
    • Type: list of strings
    • You must surround string tag values with quotes, ie ['name = "test name"']
  • filters - filters to limit included data in response with more complexity than rules

Response

A successful response will return an array of objects.

Each of the objects represents a combination of a user (specified by the "device_id" parameter) with a tag (specified by the "tag" parameter) and contains a "data" tag which is an array of arrays. Each of those arrays contains the following:

  • Index 0: Timestamp of event containing tag
  • Index 1: Tag's value in that event

Example

Request URL

/api/v2/public/devices/accounts/data_by_tag/licensee_accounts.amount,licensee_accounts.licensee

Request Body

{
limit: 1,
}

 

Response Data

[{
"tag": "licensee_accounts.amount",
"device_id": "accounts",
"data": [
["2020-01-07T01:06:31.484870+00:00", 100],
["2020-01-07T00:06:31.484870+00:00", 1]
]
},
{
"tag": "licensee_accounts.licensee",
"device_id": "accounts",
"data": [
["2020-01-07T01:06:31.484870+00:00", "ANIMAL"],
["2020-01-07T00:08:32.484870+00:00", "?"]
]
}
]

 

Update an event

This is a common endpoint used to update an event's data and is similar to the regular update event endpoint. However, some of the parameters are within the URL instead of in the request body. 

Note: If you update an event that contains a tag's last value, the last value will not be updated. Last values can only be updated by event creation.

Summary

  • Endpoint: /api/v2/public/devices/{device_id}/data/{stream}/{event_id}
  • Method: PATCH
  • Required User Type: None, this works for anyone, even if they are not a user

Path Parameters

  • device_id - string of user you want to create event for
    • Required
  • stream - stream to send data to
    • Required
  • event_id - event_id associated with event
    • Required

Body Parameters

  • event_data - data to send
    • Required
    • Type: dictionary
  • observed_at - event timestamp
    • Default: Now
    • Type: Date object or ISO-8601 date string

Response

A successful response will return the following in the "data" tag of the response:

{"message": "\n\n\n\n\n", "code": "200 OK", "title": "OK"}

Example

Request URL

/api/v2/public/devices/accounts/data/licensee_accounts/12345678

Request Body

{
event_data: {"test": "test14", "test2": 1}
}

Response Data

{"message": "\n\n\n\n\n", "code": "200 OK", "title": "OK"}

 

Get the last n values for tags

This endpoint is similar to the regular last n values endpoint. However, the parameters are within the URL instead of in the request body. 

N = 1 will have much faster performance than N > 1, so try to use N= 1 when possible. N = 1 looks up the value from a specific cached last values table while any other limit extracts the values from the entire events table.

Summary

  • Endpoint:/api/v2/public/device/{device_id}/last_n_values/{tags}/{limit}
  • Method: GET
  • Required User Type: None, this works for anyone, even if they are not a user

Path Parameters

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • device_id - user you want to query data from
    • Required
  • tags - tag to query or comma-separated list of tags to query
    • Required
  • limit - number of values to query for each tag (N)
    • Default: 1
    • Type: int

Response

A successful response will return an array of arrays in the "data" tag of the response.

Each array represents a different queried tag. These arrays contain objects of the format:

{"timestamp": <ISO string of event containing tag>, <tag>: <value>}

Example

Request URL

/api/v2/public/device/accounts/last_n_values/licensee_accounts.amount/

Response Data

[
[
{
"timestamp":"2020-01-07T01:06:31.484870+00:00",
"licensee_accounts.amount": 100
}
]
]