The following endpoints are related to event data on the IoT Platform.
Create an event
This is a common endpoint used to create a new event.
Summary
- Endpoint: /event_create
- Method: POST
- Required User Type: None, this works for all users
Body Parameters
- device_id - string of user you want to create event for
- Required
- Type: string
- Allowed users:
- Any devices linked to current tenant
- Tenant basic user
- User basic user
- If super admin/user: any user
- stream - stream to send data to
- Required
- Type: string
- 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 Body
{
device_id: 'accounts',
stream: 'licensee_accounts',
event_data: {"test": "test1234", "test2": 1}
}
Response Data
["12345678"]
Retrieve data by stream
This is a common endpoint used to query data from a stream.
Summary
- Endpoint: /device_data
- Method: GET
- Required User Type: None, this works for all users
URL 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 - string of user you want to query data from
- Required
- Allowed users:
- Any devices linked to current tenant
- Tenant basic user
- User basic user
- If super admin/user: can query from any user
- You can set more than one device_id
- stream - stream to query data from
- Required
- limit - maximum number of events to query
- Default: 1000
- Max: 10000
- since - query events that occurred no earlier than this time
- Default: Beginning of time
- Type: ISO-8601 date string
- until - query events that occurred no later than this time
- Default: Now
- Type: ISO-8601 date string
- sort_by - part of event to sort by, typically "observed_at"
- Default: None
- Required with use of "sort_direction"
- sort_direction - either "asc" or "desc"
- Default: None
- Required with use of "sort_by"
- rule - rule to limit included data in response by tag presence or equality
- Default: None
- You must surround string tag values with quotes, ie 'name = "test name"'
- You can set more than one rule
- xrule - rule to exclude data from response by tag presence or equality
- Default: None
- You must surround string tag values with quotes, ie 'name = "test name"'
- You can set more than one xrule
- 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
https://portal-example.mediumone.com/device_data?device_id=accounts&stream=licensee_accounts&limit=1
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
Instead of querying data by stream, you may want to query by tag instead.
Summary
- Endpoint: /device_data
- Method: GET
- Required User Type: None, this works for all users
URL 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 - string of user you want to query data from
- Required
- Allowed users:
- Any devices linked to current tenant
- Tenant basic user
- User basic user
- If super admin/user: can query from any user
- You can set more than one device_id
- tag - list of tags you want to query
- Required
- You can set more than one tag
- limit - maximum number of events to query
- Default: 1000
- Max: 10000
- since - query events that occurred no earlier than this time
- Default: Beginning of time
- Type: ISO-8601 date string
- until - query events that occurred no later than this time
- Default: Now
- Type: ISO-8601 date string
- sort_by - part of event to sort by, typically "observed_at"
- Default: None
- Required with use of "sort_direction"
- sort_direction - either "asc" or "desc"
- Default: None
- Required with use of "sort_by"
- rule - rule to limit included data in response by tag presence or equality
- Default: None
- You must surround string tag values with quotes, ie 'name = "test name"'
- You can set more than one rule
- xrule - rule to exclude data from response by tag presence or equality
- Default: None
- You must surround string tag values with quotes, ie 'name = "test name"'
- You can set more than one xrule
- 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
https://portal-example.mediumone.com/device_data?device_id=accounts&tag=licensee_accounts.amount&tag=licensee_accounts.licensee
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", "?"]
]
}
]
Retrieve data with a large query
The above 2 queries have a request size limit since the parameters are in the URL. If you have a large query, you can use this endpoint instead and get the same result.
Summary
- Endpoint: /device_data_post
- Method: POST
- Required User Type: None, this works for all users
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
- device_id - list of strings of each user you want to query data from
- Required
- Type: list of strings
- Allowed users:
- Any devices linked to current tenant
- Tenant basic user
- User basic user
- If super admin/user: can query from any user
- Notice that this must be a list - it cannot just be a string
- tag - tag you want to query
- Required if retrieving data by tag
- Type: list of strings
- stream - stream to query data from
- Required if retrieving data by stream
- Type: string
- limit - maximum number of events to query
- Default: 1000
- Max: 10000
- Type: int
- since - query events that occurred no earlier than this time
- Default: Beginning of time
- Type: ISO-8601 date string
- until - query events that occurred no later than this time
- Default: Now
- Type: 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
The response will be the same response as "Retrieve data by tag" or "Retrieve data by stream", depending on which argument you provided (tag vs stream)
Example
Request URL
https://portal-example.mediumone.com/device_data_post
Request Body
{
"device_id": ["accounts"],
"tag": ["licensee_accounts.amount", "licensee_accounts.licensee"]
}
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.
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: /event_update
- Method: POST
- Required User Type: None, this works for all users
Body Parameters
- device_id - string of user you want to update event for
- Required
- Type: string
- Allowed users:
- Any devices linked to current tenant
- Tenant basic user
- User basic user
- If super admin/user: any user
- stream - stream to send data to
- Required
- Type: string
- event_data - data to send
- Required
- Type: dictionary
- event_id - event_id associated with event
- Required
- Type: string
- observed_at - event timestamp
- Default: Now
- Type: Date object or ISO-8601 date string
Response
A successful response will return an empty 200 OK response.
Example
Request Body
{
device_id: 'accounts',
stream: 'licensee_accounts',
event_data: {"test": "test14", "test2": 1},
event_id: "12345678"
}
Response Data
Delete an event
Deleting events is currently not possible. See How do I delete events? for recommended strategies.