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
Name for public endpoint policy: public_create_event_v2

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
Name for public endpoint policy: public_device_data_by_stream_v2

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
- Default: None
- Type: JSON string
- See How to Build Filters

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
Name for public endpoint policy: public_device_data_by_tag_v2

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
- Default: None
- Type: JSON string
- See How to Build Filters

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
Name for public endpoint policy: public_update_event_v2

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 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.

Summary

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

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

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/device_data.val1/

Response Data

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