API Reference
The DicksonOne REST API uses predictable resource-oriented URLs, accepts both JSON-encoded and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Please Note
- If you’re maintaining an integration for the previous version (V2) of this API, you can find that documentation here. The V2 API will be deprecated at some point in the future, so we encourage you to move your integration to the new REST API.
- This code is provided “AS IS” without warranty of any kind expressed or implied. Dickson does not provide support for custom integrations.
- We’re in the process of updating our REST API responses to model JSON:API specification. You may see some objects that follow the pattern specification as detailed in the Document Structure.
Base URL
Code examples below assume that requests are being directed to endpoints for the application at a base URL. All listed request endpoints should be directed to the following domain:
https://www.dicksonone.com
Authentication
GET https://www.dicksonone.com/api/rest/users HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
The DicksonOne API uses API keys to authenticate requests. Account Managers and Owners can manage the API keys available for their account via “Manage > API Keys”. Use of this API requires that your account have an active subscription with an appropriate level of features. If you’re interested in accessing the REST API and don’t currently have access to API Key management, please contact support@dicksonone.com to discuss upgrading your subscription.
In order to access the API, you’ll need to pass the token associated with an active API Key as a Bearer
token in the Authorization
header for each request.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Pagination
Due to the large number of records that can be returned with each request, DicksonOne’s REST API uses pagination to pass back records in manageable chunks.
Request
GET https://www.dicksonone.com/api/rest/locations?page[number]=2&page[size]=3 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
For API endpoints that return a collection of results, you can control which page of results you’re fetching, as well as the number of results included on each page, using the following pagination parameters.
Parameters
Name | Description |
---|---|
page[number] | The number of the page you’re requesting. |
page[size] | The number of results you want to receive per-page. This defaults to 25, and has a maximum value of 100. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{ "id": 4, "name": "Pharmaceutical Warehouse - West", "sublocation_ids": [5, 6] },
{ "id": 5, "name": "Vaccine Refrigerator A", "sublocation_ids": [] },
{ "id": 6, "name": "Vaccine Refrigerator B", "sublocation_ids": [] }
],
"meta" : {
"pagination": {
"record_count": 7,
"page_size": 3,
"page_count": 3,
"current_page": 2,
"prev_page": 1,
"next_page": 3
}
}
}
Each response for a paginated endpoint will include a set of metadata for the paginated results, in addition to the list of record data.
Fields
Name | Description |
---|---|
data | The list of record data for the current page of results. |
meta[pagination][record_count] | The total count of records in the collection. |
meta[pagination][page_size] | The number of results included per-page. |
meta[pagination][page_count] | The total number of results pages. |
meta[pagination][current_page] | The number of the current page of results. |
meta[pagination][prev_page] | The number of the previous page of results. |
meta[pagination][next_page] | The number of the next page of results. |
Errors
DicksonOne uses conventional HTTP response codes to indicate the success or failure of an API request.
Success Codes
- Codes in the 2xx range indicate a successful response.
Code | Description |
---|---|
200 | The request was successful. |
201 | A record was created in response to the request. |
Error Codes
- Codes in the 3xx range indicate that the request needs to be redirected.
- Codes in the 4xx range indicate that the content or structure of the request is invalid (e.g., a missing or blank parameter).
- Codes in the 5xx range indicate an error on DicksonOne’s servers.
Code | Description |
---|---|
301 | The request was made via HTTP, rather than HTTPS. You will need to attempt your request again using SSL. |
400 | The request’s format was invalid. This can be triggered by invalid pagination parameters. |
401 | No API token was supplied, or the supplied API token was invalid. |
403 | The user authenticated by the API token is not permitted to perform the requested action. |
404 | The requested record wasn’t found. |
409 | Your request caused a conflict with existing data. Review the list of error messages to determine how to resolve the error. |
422 | The requested change was rejected due to validation errors. Review the list of error messages to determine how to resolve the error. |
500 | A hard-error occurred on DicksonOne’s servers. If the problem persists, please report the issue to support@dicksonone.com, with as much detail as possible. |
503 | DicksonOne is experiencing a service outage. You can try your request again in a few moments. |
Support
Dickson does not provide support for custom integrations. If you have general questions regarding access to or the functionality of the API, please email support@dicksonone.com. This code is provided “as is”, without warranty of any kind expressed or implied.
Alerts
View the alerts that have been triggered by devices on your account. Each Alert record represents a historical event that was caused by a Device tripping the warning or excursion condition for a configured Alarm.
Listing all alerts
Retrieve a list of all historical alerts for your account. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/alerts HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/alerts
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 1,
"description": "Temperature CH:1 is above 63.0°F",
"type": "high_low",
"escalation_started_at": "2022-08-08T19:22:02.000Z",
"entered_at": "2022-08-08T19:52:02.000Z",
"excursion_at": "2022-08-08T20:22:02.000Z",
"returned_to_normal_at": null,
"acknowledged_at": "2022-08-08T20:07:02.000Z",
"relationships": {
"comments": {
"data": [
],
"meta": {
"count": 0
}
}
},
"severity": "excursion",
"acknowledger": {
"id": 2,
"email": "kohler_brain@rempel.name",
"full_name": "Brain Kohler",
"first_name": "Brain",
"last_name": "Kohler",
"current_login_at": "2022-08-08T19:52:02.000Z",
"last_login_at": "2022-08-08T18:52:02.000Z",
"last_request_at": "2022-08-08T20:47:02.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
},
"location": {
"id": 1,
"name": "Hermiston-Ernser",
"sublocation_ids": [
],
"resource": "Location"
},
"device": {
"name": "Fan heater 1",
"token": "197286085837753280",
"sku": "B000HC0P2E",
"serial": "17280787d2c8bf73",
"battery": null,
"is_replaced": false,
"resource": "Device"
},
"channel": {
"id": 1,
"uuid": "82312652-4948-49c3-8130-763d0e038ccc",
"name": "Temperature CH:1",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": "2022-07-18T20:52:02.000Z",
"last_datapoint_at": "2022-08-08T20:33:02.000Z",
"resource": "Channel"
}
},
{
"id": 2,
"description": "Temperature CH:1 is above 63.0°F",
"type": "high_low",
"escalation_started_at": "2022-08-08T18:52:02.000Z",
"entered_at": "2022-08-08T19:22:02.000Z",
"excursion_at": null,
"returned_to_normal_at": "2022-08-08T19:52:02.000Z",
"acknowledged_at": null,
"relationships": {
"comments": {
"data": [
],
"meta": {
"count": 0
}
}
},
"severity": "warning",
"acknowledger": null,
"location": {
"id": 1,
"name": "Hermiston-Ernser",
"sublocation_ids": [
],
"resource": "Location"
},
"device": {
"name": "Fan heater 1",
"token": "197286085837753280",
"sku": "B000HC0P2E",
"serial": "17280787d2c8bf73",
"battery": null,
"is_replaced": false,
"resource": "Device"
},
"channel": {
"id": 1,
"uuid": "82312652-4948-49c3-8130-763d0e038ccc",
"name": "Temperature CH:1",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": "2022-07-18T20:52:02.000Z",
"last_datapoint_at": "2022-08-08T20:33:02.000Z",
"resource": "Channel"
}
}
],
"meta": {
"pagination": {
"record_count": 2,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The unique identifier for this Alert record. |
description |
The condition which resulted in the alert. |
severity |
The severity of alert. Either |
type |
The type of alert. Either |
escalation_started_at |
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert. |
entered_at |
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert. |
excursion_at |
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion. |
returned_to_normal_at |
An ISO-8601 timestamp representing the time that the alert was resolved. |
acknowledged_at |
An ISO-8601 timestamp representing the time that the alert was acknowledged. |
acknowledger |
The data for the user that acknowledged the alert. |
location |
The data for the location in which this alert took place. |
device |
The data for the device related to this alert. |
channel |
The data for the channel related to this alert. This will be null for device-level (not reporting) alerts. |
Listing filtered alerts
Retrieve a list of historical alerts for your account matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/alerts?search[tokens][]=858923900642623324&search[severity]=excursion&search[started_after]=2022-08-08T17%3A22%3A12Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/alerts
Parameters
Name | Description |
---|---|
search[tokens] |
A list of tokens for the devices to which you want to restrict your search. |
search[channel_ids] |
A list of IDs for the channels to which you want to restrict your search. |
search[location_ids] |
A list of IDs for the locations to which you want to restrict your search. |
search[active] |
Whether to specifically include only active alerts or not. Acceptable values are |
search[severity] |
The severity of alerts to which you want to restrict your search. Acceptable values are |
search[type] |
The type of alerts to which you want to restrict your search. Acceptable values are |
search[started_after] |
An ISO-8601 timestamp. Results will be filtered to alerts triggered after this time. |
search[started_before] |
An ISO-8601 timestamp. Results will be filtered to alerts triggered prior to this time. |
search[ended_after] |
An ISO-8601 timestamp. Results will be filtered to alerts resolved after this time. |
search[ended_before] |
An ISO-8601 timestamp. Results will be filtered to alerts resolved prior to this time. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 5,
"description": "Temperature CH:3 is above 99.0°F",
"type": "high_low",
"escalation_started_at": "2022-08-08T18:52:11.000Z",
"entered_at": "2022-08-08T19:22:11.000Z",
"excursion_at": "2022-08-08T19:52:11.000Z",
"returned_to_normal_at": null,
"acknowledged_at": "2022-08-08T19:37:11.000Z",
"relationships": {
"comments": {
"data": [
],
"meta": {
"count": 0
}
}
},
"severity": "excursion",
"acknowledger": {
"id": 6,
"email": "brandon.krajcik@hoeger.com",
"full_name": "Brandon Krajcik",
"first_name": "Brandon",
"last_name": "Krajcik",
"current_login_at": "2022-08-08T19:22:12.000Z",
"last_login_at": "2022-08-08T18:22:11.000Z",
"last_request_at": "2022-08-08T20:17:12.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
},
"location": {
"id": 3,
"name": "O'Connell, Nitzsche and Heaney",
"sublocation_ids": [
],
"resource": "Location"
},
"device": {
"name": "Television 3",
"token": "858923900642623324",
"sku": "B000FTBJGA",
"serial": "9c68e71816d0a9b2",
"battery": null,
"is_replaced": false,
"resource": "Device"
},
"channel": {
"id": 3,
"uuid": "2ec6b38a-0529-4309-af0e-4fc19e6bf6fc",
"name": "Temperature CH:3",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": "2022-07-18T20:22:11.000Z",
"last_datapoint_at": "2022-08-08T19:54:11.000Z",
"resource": "Channel"
}
}
],
"meta": {
"pagination": {
"record_count": 1,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The unique identifier for this Alert record. |
description |
The condition which resulted in the alert. |
severity |
The severity of alert. Either |
type |
The type of alert. Either |
escalation_started_at |
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert. |
entered_at |
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert. |
excursion_at |
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion. |
returned_to_normal_at |
An ISO-8601 timestamp representing the time that the alert was resolved. |
acknowledged_at |
An ISO-8601 timestamp representing the time that the alert was acknowledged. |
acknowledger |
The data for the user that acknowledged the alert. |
location |
The data for the location in which this alert took place. |
device |
The data for the device related to this alert. |
channel |
The data for the channel related to this alert. This will be null for device-level (not reporting) alerts. |
Getting a summary of alert counts
Retrieve counts of both active and resolved alerts for your account.
Request
GET /api/rest/alerts/summary HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/alerts/summary
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"active": 1,
"cleared": 2,
"excursion": 1,
"warning": 2
},
"meta": {
}
}
Fields
Name | Description |
---|---|
active |
An integer count of active alert records. |
cleared |
An integer count of resolved alert records. |
excursion |
An integer count of alerts with an excursion severity. |
warning |
An integer count of alerts with a warning severity. |
Summarizing filtered alert counts
Retrieve counts of both active and resolved alerts for your account matching the specified search criteria.
Request
GET /api/rest/alerts/summary?search[tokens][]=312635874990491774&search[severity]=warning&search[started_after]=2022-08-01T18%3A58%3A32Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/alerts/summary
Parameters
Name | Description |
---|---|
search[tokens] |
A list of tokens for the devices to which you want to restrict your search. |
search[channel_ids] |
A list of IDs for the channels to which you want to restrict your search. |
search[location_ids] |
A list of IDs for the locations to which you want to restrict your search. |
search[severity] |
The severity of alerts to which you want to restrict your search. Acceptable values are |
search[type] |
The type of alerts to which you want to restrict your search. Acceptable values are |
search[started_after] |
An ISO-8601 timestamp. Results will be filtered to alerts triggered after this time. |
search[started_before] |
An ISO-8601 timestamp. Results will be filtered to alerts triggered prior to this time. |
search[ended_after] |
An ISO-8601 timestamp. Results will be filtered to alerts resolved after this time. |
search[ended_before] |
An ISO-8601 timestamp. Results will be filtered to alerts resolved prior to this time. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"active": 1,
"cleared": 1,
"excursion": 0,
"warning": 2
},
"meta": {
}
}
Fields
Name | Description |
---|---|
active |
An integer count of active alert records. |
cleared |
An integer count of resolved alert records. |
excursion |
An integer count of alerts with an excursion severity. |
warning |
An integer count of alerts with a warning severity. |
Acknowledging an alert
Mark an alert as acknowledged. The acknowledger
for the alert will
be set to the User associated with the API token, and the
acknowledged_at
timestamp will be set to the time that the request
was received by the server. Attempting to acknowledge an alert that
has already been acknowledged will result in a 409 Conflict response.
Request
POST /api/rest/alerts/13/acknowledgements HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
POST /api/rest/alerts/:alert_id/acknowledgements
Response
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 13,
"description": "Temperature CH:6 is above 46.0°F",
"type": "high_low",
"escalation_started_at": "2022-08-08T19:22:07.000Z",
"entered_at": "2022-08-08T19:52:07.000Z",
"excursion_at": "2022-08-08T20:22:07.000Z",
"returned_to_normal_at": null,
"acknowledged_at": "2022-08-08T20:52:07.000Z",
"relationships": {
"comments": {
"data": [
{
"type": "comment",
"id": "7"
}
],
"meta": {
"count": 1
}
}
},
"severity": "excursion",
"acknowledger": {
"id": 9,
"email": "bruen.roselia@kutch.co",
"full_name": "Roselia Bruen",
"first_name": "Roselia",
"last_name": "Bruen",
"current_login_at": "2022-08-08T19:52:07.000Z",
"last_login_at": "2022-08-07T20:52:07.000Z",
"last_request_at": "2022-08-08T20:52:07.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager"
},
"location": {
"id": 6,
"name": "Herman, Walker and Kuhlman",
"sublocation_ids": [
],
"resource": "Location"
},
"device": {
"name": "Water purifier 6",
"token": "427001073922713645",
"sku": "B0000DGITY",
"serial": "9462adaeafc2b52d",
"battery": null,
"is_replaced": false,
"resource": "Device"
},
"channel": {
"id": 6,
"uuid": "c6e05b4c-3a78-4c3f-9daa-b04355e05cf8",
"name": "Temperature CH:6",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": "2022-07-04T20:52:07.000Z",
"last_datapoint_at": "2022-08-08T20:26:07.000Z",
"resource": "Channel"
}
}
}
Fields
Name | Description |
---|---|
id |
The unique identifier for this Alert record. |
description |
The condition which resulted in the alert. |
severity |
The severity of alert. Either |
type |
The type of alert. Either |
escalation_started_at |
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert. |
entered_at |
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert. |
excursion_at |
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion. |
returned_to_normal_at |
An ISO-8601 timestamp representing the time that the alert was resolved. |
acknowledged_at |
An ISO-8601 timestamp representing the time that the alert was acknowledged. |
acknowledger |
The data for the user that acknowledged the alert. |
location |
The data for the location in which this alert took place. |
device |
The data for the device related to this alert. |
channel |
The data for the channel related to this alert. This will be null for device-level (not reporting) alerts. |
Listing comments for an alert
Retrieve a list of comments that have been submitted for a particular alert. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/alerts/1/comments HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/alerts/:alert_id/comments
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 1,
"text": "Corrupti enim soluta. Libero cupiditate quis.",
"created_at": "2021-08-04T02:33:38.000Z",
"user": {
"id": 2,
"email": "feest_julia@roberts.biz",
"full_name": "Julia Feest",
"first_name": "Julia",
"last_name": "Feest",
"current_login_at": "2021-08-04T01:33:38.000Z",
"last_login_at": "2021-08-03T02:33:38.000Z",
"last_request_at": "2021-08-04T02:28:38.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
},
{
"id": 2,
"text": "Vero quo mollitia. Fugiat aut aut.",
"created_at": "2021-08-04T02:33:38.000Z",
"user": {
"id": 2,
"email": "feest_julia@roberts.biz",
"full_name": "Julia Feest",
"first_name": "Julia",
"last_name": "Feest",
"current_login_at": "2021-08-04T01:33:38.000Z",
"last_login_at": "2021-08-03T02:33:38.000Z",
"last_request_at": "2021-08-04T02:28:38.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
},
{
"id": 3,
"text": "Qui debitis minus. Vitae sit eveniet.",
"created_at": "2021-08-04T02:33:38.000Z",
"user": {
"id": 2,
"email": "feest_julia@roberts.biz",
"full_name": "Julia Feest",
"first_name": "Julia",
"last_name": "Feest",
"current_login_at": "2021-08-04T01:33:38.000Z",
"last_login_at": "2021-08-03T02:33:38.000Z",
"last_request_at": "2021-08-04T02:28:38.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
}
],
"meta": {
"pagination": {
"record_count": 3,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The unique identifier for this Comment record. |
text |
The text content of the Comment. |
created_at |
An ISO-8601 timestamp representing the time that the Comment was made. |
user |
The data for the user that submitted the Comment. |
Adding a comment to an alert
Add a comment to a specified Alert. If the Alert was not previously acknowledged, this action will also acknowledge the alert and mark the commenter as the acknowledger.
Request
POST /api/rest/alerts/1/comments HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"comment": {
"text": "Consequatur ad aperiam. Excepturi tenetur sed. Et doloremque non."
}
}
Endpoint
POST /api/rest/alerts/:alert_id/comments
Parameters
Name | Description |
---|---|
comment[text] |
The text content for the new Comment. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 1,
"text": "Consequatur ad aperiam. Excepturi tenetur sed. Et doloremque non.",
"created_at": "2021-08-04T02:33:39.000Z",
"user": {
"id": 1,
"email": "christin.abbott@bergnaum.io",
"full_name": "Christin Abbott",
"first_name": "Christin",
"last_name": "Abbott",
"current_login_at": "2021-08-04T01:33:38.000Z",
"last_login_at": "2021-08-03T02:33:38.000Z",
"last_request_at": "2021-08-04T02:28:38.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager"
}
}
}
Fields
Name | Description |
---|---|
id |
The unique identifier for the new Comment record. |
text |
The text content of the Comment. |
created_at |
An ISO-8601 timestamp representing the time that the Comment was made. |
user |
The data for the user that submitted the Comment. |
Channels
View the channels reporting for the devices on your account. Each Channel record represents a single stream of data coming in from a sensor plugged in to one of your environmental loggers. One sensor can potentially report multiple Channels’ worth of data to DicksonOne.
Fetching channel data
Readings data for DicksonOne is served out of a separate Datapoint Service. When you fetch information for a channel, the response includes the URLs necessary to fetch the data for that channel.
All readings data is normalized to a single unit for storage purposes (e.g., all temperature readings are stored in Fahrenheit). When you view your data in exports, reports, or the DicksonOne interface, we perform a conversion from the stored unit to the display unit configured for your device. If you’re building a custom integration and want to see the readings values in a different unit, you’ll need to convert the raw readings data yourself.
Summary data
GET https://dps.dicksonone.com/datapoints/036390d0-f790-4cf6-b903-cc0ee63f49b7/1566364361/1566450761/summary HTTP/1.1
The summary_url
for a channel gives a full summary of the data for the
channel over its reporting lifetime.
Summary response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"summary":{
"count": 289,
"min": 13.9,
"max": 15.1,
"avg": 14.5764705882353,
"mkt": 14.5800856751846,
"min_ts": 1566385361,
"max_ts": 1566447761,
"unit":"f"
}
}
Fields
Name | Description |
---|---|
count | The total number of readings submitted for the channel. |
min | The minimum reading value recorded for the channel. |
min_ts | An integer epoch timestamp representing the time of the minimum reading value. |
max | The maximum reading value recorded for the channel. |
max_ts | An integer epoch timestamp representing the time of the maximum reading value. |
avg | The average reading value recorded for the channel. |
mkt | An estimated Mean Kinetic Temperature for the channel. This is included in every summary, but only valid for Temperature channels. |
unit | The unit in which the readings are stored. |
Readings data
GET https://dps.dicksonone.com/datapoints/036390d0-f790-4cf6-b903-cc0ee63f49b7/1566364361/1566365561 HTTP/1.1
The readings_urls
for a channel lists a series of URLs for segments of
data. Fetching the data at these URLs will yield all of the readings that
have been recorded for the channel over its reporting lifetime.
Readings response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"records":[
{"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364361, "value": 14.5, "unit": "f"},
{"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364661, "value": 14.6, "unit": "f"},
{"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364961, "value": 14.8, "unit": "f"},
{"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566365261, "value": 14.9, "unit": "f"},
{"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566365561, "value": 14.5, "unit": "f"}
]
}
Fields
Name | Description |
---|---|
channel | A unique identifier used to store the readings for the channel. |
ts | An integer epoch timestamp representing the time that the reading was recorded. |
value | The reading value that was recorded by the logger. |
unit | The unit in which the reading is stored. |
Listing account channels
Retrieve a list of all channels reporting for devices belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/channels HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/channels
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 10,
"uuid": "75d7b2f1-aa99-4e9a-abe2-aed1adb3b76b",
"name": "Relative Humidity CH:10",
"type": "RelativeHumidity",
"unit": "rh",
"first_datapoint_at": "2022-07-25T20:52:09.000Z",
"last_datapoint_at": "2022-08-08T20:49:09.000Z",
"resource": "Channel",
"device": {
"name": "Steam mop 12",
"token": "531980225160492650",
"sku": "B000I6QR9O",
"serial": "a68dea638c831029",
"battery": null,
"is_replaced": false,
"resource": "Device"
},
"location": {
"id": 11,
"name": "Legros-West",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
},
{
"id": 9,
"uuid": "750c2070-717c-44c3-b20c-f0c844cd3257",
"name": "Temperature CH:9",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": "2022-08-01T20:52:09.000Z",
"last_datapoint_at": "2022-08-08T20:41:09.000Z",
"resource": "Channel",
"device": {
"name": "Window fan 11",
"token": "838710545662032066",
"sku": "B000AXVVY6",
"serial": "4d59a9e93ca9c6c3",
"battery": null,
"is_replaced": false,
"resource": "Device"
},
"location": {
"id": 11,
"name": "Legros-West",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
{
"type": "alert",
"id": "18"
}
],
"meta": {
"count": 1
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "17"
}
],
"meta": {
"count": 1
}
}
}
}
],
"meta": {
"pagination": {
"record_count": 2,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The channel’s unique identifier. |
uuid |
The channel’s identifier with the datapoint service. |
name |
The channel’s name. |
type |
The type of channel, e.g., Temperature or RelativeHumidity. |
unit |
The unit for readings reported to the channel, e.g., Fahrenheit or Celsius. |
first_datapoint_at |
The ISO-8601 timestamp of the first reading submitted to the channel. |
last_datapoint_at |
The ISO-8601 timestamp of the most recent reading submitted to the channel. |
location |
The location where this channel is being used. |
device |
The device that is associated with this channel. |
Listing filtered channels
Retrieve a list of all channels for your account matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/channels?search[name]=Temperature+CH%3A8 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/channels
Parameters
Name | Description |
---|---|
search[name] |
A partial name for channels to which you want to restrict your search. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 1,
"uuid": "7913f2dc-54ac-4de5-897e-13b924f93d11",
"name": "Temperature CH:8",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2021-11-19T16:05:52.000Z",
"last_datapoint_at": "2021-11-19T15:36:52.000Z",
"resource": "Channel",
"relationships": {
"warnings": {
"data": [
{
"type": "alert",
"id": "3"
}
],
"meta": {
"count": 1
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "2"
}
],
"meta": {
"count": 1
}
}
},
"device": {
"name": "Mousetrap 12",
"token": "685523701899205820",
"sku": "B000662SOY",
"serial": "b0dae9df385b9c9a",
"battery": null,
"is_replaced": false,
"resource": "Device"
},
"location": {
"id": 1,
"name": "Monahan and Sons",
"sublocation_ids": [
],
"resource": "Location",
"relationships": {
"warnings": {
"data": [
{
"type": "alert",
"id": "3"
}
],
"meta": {
"count": 1
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "2"
}
],
"meta": {
"count": 1
}
}
}
}
}
],
"meta": {
"pagination": {
"record_count": 1,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The channel’s unique identifier. |
uuid |
The channel’s identifier with the datapoint service. |
name |
The channel’s name. |
type |
The type of channel, e.g., Temperature or RelativeHumidity. |
unit |
The unit for readings reported to the channel, e.g., Fahrenheit or Celsius. |
first_datapoint_at |
The ISO-8601 timestamp of the first reading submitted to the channel. |
last_datapoint_at |
The ISO-8601 timestamp of the most recent reading submitted to the channel. |
location |
The location where this channel is being used. |
device |
The device that is associated with this channel. |
Listing channels by device
Retrieve a list of the channels reporting for a specific device. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices/648289742548712166/channels HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices/:token/channels
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 13,
"uuid": "472842c5-92f1-4d57-aae3-fea7c781de4c",
"name": "Temperature CH:13",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": "2022-07-13T00:05:48.000Z",
"last_datapoint_at": "2022-08-09T23:51:48.000Z",
"resource": "Channel",
"device": {
"name": "Trouser press 15",
"token": "648289742548712166",
"sku": "B0000DDZ3N",
"serial": "2fbf7e71717d2794",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
},
"location": {
"id": 13,
"name": "Sawayn-Funk",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
}
],
"meta": {
"pagination": {
"record_count": 1,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The channel’s unique identifier. |
uuid |
The channel’s identifier with the datapoint service. |
name |
The channel’s name. |
type |
The type of channel, e.g., Temperature or RelativeHumidity. |
unit |
The unit for readings reported to the channel, e.g., Fahrenheit or Celsius. |
first_datapoint_at |
The ISO-8601 timestamp of the first reading submitted to the channel. |
last_datapoint_at |
The ISO-8601 timestamp of the most recent reading submitted to the channel. |
Fetching a specific channel
By requesting details for a single channel, you can see more information, including URLs from which you can fetch readings and summary data for the device.
Request
GET /api/rest/channels/15?readings[after]=2022-08-05T00%3A05%3A50Z&readings[before]=2022-08-06T00%3A05%3A50Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/channels/:id
Parameters
Name | Description |
---|---|
readings[after] |
An ISO-8601 timestamp. Summary and readings URLs will reflect readings captured after this time. |
readings[before] |
An ISO-8601 timestamp. Summary and readings URLs will reflect readings captured prior to this time. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 15,
"uuid": "54ba0249-f3b9-425e-9919-60a0c35a75aa",
"name": "Differential Pressure CH:15",
"type": "DifferentialPressure",
"unit": "inches_h2o",
"first_datapoint_at": "2022-07-27T00:05:50.000Z",
"last_datapoint_at": "2022-08-09T23:51:50.000Z",
"resource": "Channel",
"summary_url": "http://localhost:4001/datapoints/54ba0249-f3b9-425e-9919-60a0c35a75aa/1659657950/1659744350/summary",
"readings_urls": [
"http://localhost:4001/datapoints/54ba0249-f3b9-425e-9919-60a0c35a75aa/1659657950/1659744350"
],
"device": {
"name": "Clothes iron 16",
"token": "798303650837513479",
"sku": "B000A1D15U",
"serial": "d7c97137d6ff8f9e",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
},
"location": {
"id": 14,
"name": "Schumm-Rolfson",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
}
}
Fields
Name | Description |
---|---|
id |
The channel’s unique identifier. |
uuid |
The channel’s identifier with the datapoint service. |
name |
The channel’s name. |
type |
The type of channel, e.g., Temperature or RelativeHumidity. |
unit |
The unit for readings reported to the channel, e.g., Fahrenheit or Celsius. |
first_datapoint_at |
The ISO-8601 timestamp of the first reading submitted to the channel. |
last_datapoint_at |
The ISO-8601 timestamp of the most recent reading submitted to the channel. |
summary_url |
A URL from which to fetch a summary of the recent readings data for the channel. |
readings_urls |
A list of URLs from which to fetch readings data. |
location |
The location where this channel is being used. |
device |
The device that is associated with this channel. |
Listing annotations for a channel
Retrieve a list of all annotations added to a specific channel. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/channels/16/annotations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/channels/:channel_id/annotations
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 1,
"content": "Et minima non. Officia dolorum animi.",
"at": "2022-07-08T20:52:11.000Z",
"channel": {
"id": 16,
"uuid": "41fe3c3e-338a-4cf9-b3c5-37c5394764d8",
"name": "Temperature CH:16",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel"
},
"user": {
"id": 18,
"email": "jacobson.williemae@beahan.org",
"full_name": "Williemae Jacobson",
"first_name": "Williemae",
"last_name": "Jacobson",
"current_login_at": "2022-08-08T19:52:11.000Z",
"last_login_at": "2022-08-07T20:52:11.000Z",
"last_request_at": "2022-08-08T20:47:11.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
},
{
"id": 2,
"content": "Veritatis itaque quia. Vel ipsum quo.",
"at": "2022-07-25T20:52:11.000Z",
"channel": {
"id": 16,
"uuid": "41fe3c3e-338a-4cf9-b3c5-37c5394764d8",
"name": "Temperature CH:16",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel"
},
"user": {
"id": 19,
"email": "haley.zachary@lueilwitz-schumm.org",
"full_name": "Zachary Haley",
"first_name": "Zachary",
"last_name": "Haley",
"current_login_at": "2022-08-08T19:52:12.000Z",
"last_login_at": "2022-08-07T20:52:12.000Z",
"last_request_at": "2022-08-08T20:47:12.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
}
],
"meta": {
"pagination": {
"record_count": 2,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The annotation’s unique identifier. |
content |
The text content of the annotation. |
at |
The ISO-8601 timestamp for the annotation’s place on the channel’s timeline. |
user |
The data for the user that added the annotation. |
Listing filtered annotations
Retrieve a list of annotations for the channel matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/channels/19/annotations?search[after]=2022-06-30T18%3A28%3A46Z&search[before]=2022-07-14T18%3A28%3A46Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/channels/:channel_id/annotations
Parameters
Name | Description |
---|---|
search[after] |
An ISO-8601 timestamp. Results will be filtered to annotations added after this time. |
search[before] |
An ISO-8601 timestamp. Results will be filtered to annotations added prior to this time. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 3,
"content": "Ad sit et. Molestiae omnis omnis.",
"at": "2022-07-04T18:28:45.000Z",
"channel": {
"id": 19,
"uuid": "c85a8f9d-681e-40e2-9526-267564525e20",
"name": "Temperature CH:19",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
},
"user": {
"id": 21,
"email": "kerry.dietrich@rippin.com",
"full_name": "Kerry Dietrich",
"first_name": "Kerry",
"last_name": "Dietrich",
"current_login_at": "2022-08-04T17:28:45.000Z",
"last_login_at": "2022-08-03T18:28:45.000Z",
"last_request_at": "2022-08-04T18:23:45.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
}
],
"meta": {
"pagination": {
"record_count": 1,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The annotation’s unique identifier. |
content |
The text content of the annotation. |
at |
The ISO-8601 timestamp for the annotation’s place on the channel’s timeline. |
user |
The data for the user that added the annotation. |
Adding a channel annotation
Add an annotation to the specified channel, at the specified time. Any added annotations will show up when the relevant time period is rendered on a Device Overview graph.
Request
POST /api/rest/channels/22/annotations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"annotation": {
"content": "Praesentium facere deserunt. Quibusdam qui cumque. Animi praesentium dolores.",
"at": "2022-08-01T20:22:19Z"
}
}
Endpoint
POST /api/rest/channels/:channel_id/annotations
Parameters
Name | Description |
---|---|
annotation[content] |
The text content to set for the new annotation. |
annotation[at] |
An ISO-8601 timestamp for the time relevant to the annotation. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 5,
"content": "Praesentium facere deserunt. Quibusdam qui cumque. Animi praesentium dolores.",
"at": "2022-08-01T20:22:19.000Z",
"channel": {
"id": 22,
"uuid": "6d740674-2be9-4213-8b95-9d862943c43e",
"name": "Temperature CH:22",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel"
},
"user": {
"id": 23,
"email": "senger.larry@pfeffer.info",
"full_name": "Larry Senger",
"first_name": "Larry",
"last_name": "Senger",
"current_login_at": "2022-08-08T19:22:19.000Z",
"last_login_at": "2022-08-07T20:22:19.000Z",
"last_request_at": "2022-08-08T20:22:19.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager"
}
}
}
Fields
Name | Description |
---|---|
id |
The new annotation’s unique identifier. |
content |
The text content of the new annotation. |
at |
The ISO-8601 timestamp for the new annotation’s place on the channel’s timeline. |
user |
The data for the user that added the annotation. |
Updating a channel annotation
Update the specified annotation with new content or a modified timestamp.
Request
PATCH /api/rest/channels/1/annotations/1 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"annotation": {
"content": "Ad voluptatum nihil. Ut eum quia. Ut quia architecto."
}
}
Endpoint
PATCH /api/rest/channels/:channel_id/annotations/:id
Parameters
Name | Description |
---|---|
annotation[content] |
The new text content to set for the new annotation. |
annotation[at] |
An updated ISO-8601 timestamp for the annotation. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 1,
"content": "Ad voluptatum nihil. Ut eum quia. Ut quia architecto.",
"at": "2021-11-19T16:06:01.000Z",
"channel": {
"id": 1,
"uuid": "9da2c7b6-bb30-4780-9990-b0757a917bc2",
"name": "Temperature CH:20",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
},
"user": {
"id": 2,
"email": "kuhn.maura@runolfsson-funk.name",
"full_name": "Maura Kuhn",
"first_name": "Maura",
"last_name": "Kuhn",
"current_login_at": "2021-11-19T15:06:01.000Z",
"last_login_at": "2021-11-18T16:06:01.000Z",
"last_request_at": "2021-11-19T16:01:01.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
}
}
Fields
Name | Description |
---|---|
id |
The annotation’s unique identifier. |
content |
The updated text content of the annotation. |
at |
The updated ISO-8601 timestamp for the annotation. |
user |
The data for the user that added the annotation. |
Removing a channel annotation
Delete the specified annotation.
Request
DELETE /api/rest/channels/1/annotations/1 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
DELETE /api/rest/channels/:channel_id/annotations/:id
Devices
View the devices configured for your account. Each Device record represents
the current status of a particular environmental logger. Instead of integer
IDs, Devices are thus accessed using a string token
, which is maintained
across device replacements.
Listing account devices
Retrieve a list of all devices belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"name": "Futon dryer 22",
"token": "627535976179211739",
"sku": "B0002XTOHK",
"serial": "b1753e437e9857a3",
"battery": 2,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 26,
"name": "Thompson, Morar and Blick",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Back boiler 23",
"token": "113243063505900390",
"sku": "B000AF8T1C",
"serial": "2984a09f1676f097",
"battery": 2,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 26,
"name": "Thompson, Morar and Blick",
"sublocation_ids": [
],
"resource": "Location"
}
}
],
"meta": {
"pagination": {
"record_count": 2,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
token |
The device’s unique identifier. This value is maintained across device replacements. |
name |
The device’s name. |
sku |
The device’s model/SKU. |
serial |
The device’s serial number. |
battery |
The device’s current battery level, represented as an integer between 0 and 5. Only present for supported devices. |
location |
The location where this device is being used. |
Listing replaced devices
Retrieve a list of all devices belonging to your account, including older device serials that have been replaced. This list is paginated.
Request
GET /api/rest/devices?search[include_replacements]=true HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices
Parameters
Name | Description |
---|---|
search[include_replacements] |
A boolean. Results will be expanded to include replaced devices if true. Defaults to false. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"name": "Attic fan 24",
"token": "813315952515283602",
"sku": "B000HW1EGK",
"serial": "a301a6b67e06dbc7",
"battery": 2,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 27,
"name": "Tromp LLC",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Blender 25",
"token": "932500552888491135",
"sku": "B000HU7P92",
"serial": "8f70b0ff7942658b",
"battery": 2,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 27,
"name": "Tromp LLC",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Aroma lamp 26",
"token": "813315952515283602",
"sku": "B000A2NCLW",
"serial": "92a2af612a296ee3",
"battery": null,
"is_replaced": true,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 27,
"name": "Tromp LLC",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Hob (hearth) 27",
"token": "813315952515283602",
"sku": "B000A2T37E",
"serial": "06af3417e4f24550",
"battery": null,
"is_replaced": true,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 27,
"name": "Tromp LLC",
"sublocation_ids": [
],
"resource": "Location"
}
}
],
"meta": {
"pagination": {
"record_count": 4,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
token |
The device’s unique identifier. This value is maintained across device replacements. |
name |
The device’s name. |
sku |
The device’s model/SKU. |
serial |
The device’s serial number. |
battery |
The device’s current battery level, represented as an integer between 0 and 5. Only present for supported devices. |
location |
The location where this device is being used. |
is_replaced |
A boolean indicating whether or not the device has been replaced. |
Listing filtered devices
Retrieve a list of all devices for your account matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices?search[name]=Fridge HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices
Parameters
Name | Description |
---|---|
search[name] |
A partial name for devices to which you want to restrict your search. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"name": "Fridge",
"token": "524739378145621279",
"sku": "B000N5FYOE",
"serial": "332e25d7fc59d501",
"battery": 2,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 28,
"name": "Gottlieb-Lind",
"sublocation_ids": [
],
"resource": "Location"
}
}
],
"meta": {
"pagination": {
"record_count": 1,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
token |
The device’s unique identifier. This value is maintained across device replacements. |
name |
The device’s name. |
sku |
The device’s model/SKU. |
serial |
The device’s serial number. |
battery |
The device’s current battery level, represented as an integer between 0 and 5. Only present for supported devices. |
location |
The location where this device is being used. |
Listing devices by location
Retrieve a list of the devices attached to a specific location. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/locations/33/devices HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/locations/:location_id/devices
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"name": "Flame supervision device 30",
"token": "913670665231524956",
"sku": "B000HGNY7I",
"serial": "58617c6db829be77",
"battery": 4,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 33,
"name": "Drawing Room 3",
"sublocation_ids": [
],
"resource": "Location"
}
}
],
"meta": {
"pagination": {
"record_count": 1,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
token |
The device’s unique identifier. This value is maintained across device replacements. |
name |
The device’s name. |
sku |
The device’s model/SKU. |
serial |
The device’s serial number. |
battery |
The device’s current battery level, represented as an integer between 0 and 5. Only present for supported devices. |
Fetching a specific device
By requesting details for a single device, you can see more information, including the channel metadata for that device.
Request
GET /api/rest/devices/262993413474352805 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices/:token
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"name": "Evaporative cooler 31",
"token": "262993413474352805",
"sku": "B000ML8E7I",
"serial": "6932f78fbe783fd2",
"battery": 3,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 2
}
}
},
"channels": [
{
"id": 29,
"uuid": "f5f7ee86-efc2-4b9e-8877-5d10ed4e8159",
"name": "Temperature CH:29",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": "2022-07-27T00:05:57.000Z",
"last_datapoint_at": "2022-08-09T23:41:57.000Z",
"resource": "Channel"
},
{
"id": 30,
"uuid": "81bf40b7-1349-4195-ba13-b00a39196121",
"name": "Temperature CH:30",
"type": "Temperature",
"unit": "f",
"first_datapoint_at": "2022-07-06T00:05:57.000Z",
"last_datapoint_at": "2022-08-09T23:43:57.000Z",
"resource": "Channel"
}
],
"location": {
"id": 34,
"name": "Carroll, Runolfsson and Jast",
"sublocation_ids": [
],
"resource": "Location"
}
}
}
Fields
Name | Description |
---|---|
token |
The device’s unique identifier. This value is maintained across device replacements. |
name |
The device’s name. |
sku |
The device’s model/SKU. |
serial |
The device’s serial number. |
battery |
The device’s current battery level, represented as an integer between 0 and 5. Only present for supported devices. |
channels |
A list of channels reporting for the device. |
location |
The location where this device is being used. |
Listing annotations for a device
Retrieve a list of all annotations added to channels on a specific device. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices/443132679582266646/annotations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices/:token/annotations
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 1,
"content": "Quia voluptatibus odio. Corporis impedit aliquam.",
"at": "2021-10-19T22:07:49.000Z",
"channel": {
"id": 1,
"uuid": "cb098604-dbda-4285-9974-0ed7119bfb48",
"name": "Temperature CH:28",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
},
"user": {
"id": 2,
"email": "rice_yoko@simonis-windler.name",
"full_name": "Yoko Rice",
"first_name": "Yoko",
"last_name": "Rice",
"current_login_at": "2021-11-19T21:07:49.000Z",
"last_login_at": "2021-11-18T22:07:49.000Z",
"last_request_at": "2021-11-19T22:02:49.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
},
{
"id": 2,
"content": "Totam et qui. Officiis sint placeat.",
"at": "2021-11-05T22:07:49.000Z",
"channel": {
"id": 2,
"uuid": "5bb7d458-4b5a-4653-bce4-58efb81a5923",
"name": "Temperature CH:29",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
},
"user": {
"id": 3,
"email": "jimmie.cummings@weber-emard.biz",
"full_name": "Jimmie Cummings",
"first_name": "Jimmie",
"last_name": "Cummings",
"current_login_at": "2021-11-19T21:07:49.000Z",
"last_login_at": "2021-11-18T22:07:49.000Z",
"last_request_at": "2021-11-19T22:02:49.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
}
],
"meta": {
"pagination": {
"record_count": 2,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The annotation’s unique identifier. |
content |
The text content of the annotation. |
at |
The ISO-8601 timestamp for the annotation’s place on the channel’s timeline. |
user |
The data for the user that added the annotation. |
channel |
The data for the channel on which the annotation was added. |
Listing filtered device annotations
Retrieve a list of annotations for the device matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices/369196175540882713/annotations?search[after]=2021-10-15T22%3A07%3A51Z&search[before]=2021-10-29T22%3A07%3A51Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices/:token/annotations
Parameters
Name | Description |
---|---|
search[after] |
An ISO-8601 timestamp. Results will be filtered to annotations added after this time. |
search[before] |
An ISO-8601 timestamp. Results will be filtered to annotations added prior to this time. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 1,
"content": "Maxime voluptates nesciunt. Excepturi rerum modi.",
"at": "2021-10-19T22:07:50.000Z",
"channel": {
"id": 1,
"uuid": "ce703674-e874-42d3-a35b-13ea982088cd",
"name": "Temperature CH:32",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
},
"user": {
"id": 2,
"email": "deckow.janella@ritchie.net",
"full_name": "Janella Deckow",
"first_name": "Janella",
"last_name": "Deckow",
"current_login_at": "2021-11-19T21:07:50.000Z",
"last_login_at": "2021-11-18T22:07:50.000Z",
"last_request_at": "2021-11-19T22:02:50.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null
}
}
],
"meta": {
"pagination": {
"record_count": 1,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The annotation’s unique identifier. |
content |
The text content of the annotation. |
at |
The ISO-8601 timestamp for the annotation’s place on the channel’s timeline. |
user |
The data for the user that added the annotation. |
channel |
The data for the channel on which the annotation was added. |
Events
View the event logs for your account. Each record represents an event that took place on the account. Events can take multiple formats.
Supported event types
There are multiple types of activity captured in the event logs for an
account. The type of activity is exposed in the type
field in each
response, and the list of events can be filtered by supplying one of these
values for the search[type]
parameter.
Name | Description |
---|---|
Account | Activity tied to registration of an account, or settings updates. |
Alarm | Activity tied to the creation, update, or triggering of alarms. |
Annotation | Activity tied to the creation, update, or removal of channel annotations. |
ApiKey | Activity tied to the generation and revocation of API keys. |
Contact | Activity tied to the creation or modification of user/contact information. |
Device | Activity tied to the registration of a device or update of device settings. |
EscalationPolicy | Activity tied to the creation or update of notification policies on the account. |
Export | Activity tied to generation of account or device exports for the account. |
Location | Activity tied to the management of Locations on the account. |
Report | Activity tied to the creation, update, or generation of a report. |
Subscription | Activity tied to redemption or update of a Subscription for the account. |
TemplateGroup | Activity tied to the creation or update of an alarm template. |
Listing all events
Retrieve a list of all events for your account, in reverse chronological order. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/events HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/events
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 7,
"message": "Device setting(s) updated:\n - Temperature Display Unit changed to \"°C\" from \"°F\"",
"created_at": "2022-08-09T23:36:00.000Z",
"type": "Device",
"user": {
"id": 40,
"email": "lebsack.caroll@gerhold.io",
"full_name": "Caroll Lebsack",
"first_name": "Caroll",
"last_name": "Lebsack",
"current_login_at": "2022-08-09T23:06:00.000Z",
"last_login_at": "2022-08-09T00:06:00.000Z",
"last_request_at": "2022-08-10T00:06:00.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager"
},
"device": {
"name": "Icebox 34",
"token": "755650094395157199",
"sku": "B0000DGI28",
"serial": "ccdd4f8aea2f07e0",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
}
},
"location": {
"id": 41,
"name": "Quigley-Tromp",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"id": 6,
"message": "Logged In",
"created_at": "2022-08-09T23:16:00.000Z",
"type": "User",
"user": {
"id": 40,
"email": "lebsack.caroll@gerhold.io",
"full_name": "Caroll Lebsack",
"first_name": "Caroll",
"last_name": "Lebsack",
"current_login_at": "2022-08-09T23:06:00.000Z",
"last_login_at": "2022-08-09T00:06:00.000Z",
"last_request_at": "2022-08-10T00:06:00.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager"
},
"device": null,
"location": null
},
{
"id": 5,
"message": "Failed Login Attempt",
"created_at": "2022-08-09T23:06:00.000Z",
"type": "User",
"user": {
"id": 40,
"email": "lebsack.caroll@gerhold.io",
"full_name": "Caroll Lebsack",
"first_name": "Caroll",
"last_name": "Lebsack",
"current_login_at": "2022-08-09T23:06:00.000Z",
"last_login_at": "2022-08-09T00:06:00.000Z",
"last_request_at": "2022-08-10T00:06:00.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager"
},
"device": null,
"location": null
}
],
"meta": {
"pagination": {
"record_count": 3,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The unique identifier for this Event record. |
message |
A description of the event that took place. |
type |
The type of event. |
created_at |
An ISO-8601 timestamp representing the time that the event took place. |
user |
The data for the user responsible for this event. |
device |
The data for the device related to this event. |
location |
The data for the location related to this event. |
Listing filtered events
Retrieve a list of all events for your account matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/events?search[user_ids][]=1&search[type][]=Contact HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/events
Parameters
Name | Description |
---|---|
search[tokens] |
A list of tokens for the devices to which you want to restrict your search. |
search[user_ids] |
A list of IDs for the users to which you want to restrict your search. |
search[location_ids] |
A list of IDs for the locations containing devices to which you want to restrict your search. |
search[type] |
The type(s) of event to which you want to restrict your search. See above for acceptable values. |
search[after] |
An ISO-8601 timestamp. Results will be filtered to events that took place after this time. |
search[before] |
An ISO-8601 timestamp. Results will be filtered to events that took place prior to this time. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 2,
"message": "Logged In",
"created_at": "2021-08-04T01:43:49.000Z",
"type": "User",
"user": {
"id": 1,
"email": "claudia_wolf@christiansen.co",
"full_name": "Claudia Wolf",
"first_name": "Claudia",
"last_name": "Wolf",
"current_login_at": "2021-08-04T01:33:49.000Z",
"last_login_at": "2021-08-03T02:33:49.000Z",
"last_request_at": "2021-08-04T02:28:49.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager"
},
"device": null,
"location": null
},
{
"id": 1,
"message": "Failed Login Attempt",
"created_at": "2021-08-04T01:33:49.000Z",
"type": "User",
"user": {
"id": 1,
"email": "claudia_wolf@christiansen.co",
"full_name": "Claudia Wolf",
"first_name": "Claudia",
"last_name": "Wolf",
"current_login_at": "2021-08-04T01:33:49.000Z",
"last_login_at": "2021-08-03T02:33:49.000Z",
"last_request_at": "2021-08-04T02:28:49.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager"
},
"device": null,
"location": null
}
],
"meta": {
"pagination": {
"record_count": 2,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The unique identifier for this Event record. |
message |
A description of the event that took place. |
type |
The type of event. |
created_at |
An ISO-8601 timestamp representing the time that the event took place. |
user |
The data for the user responsible for this event. |
device |
The data for the device related to this event. |
location |
The data for the location related to this event. |
Searching for an invalid event type
Attempting to filter the list of results with an unsupported
search[type]
(see above for the list of
supported types) will result in a 400 error.
Request
GET /api/rest/events?search[type]=Other HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/events
Parameters
Name | Description |
---|---|
search[tokens] |
A list of tokens for the devices to which you want to restrict your search. |
search[user_ids] |
A list of IDs for the users to which you want to restrict your search. |
search[location_ids] |
A list of IDs for the locations containing devices to which you want to restrict your search. |
search[type] |
The type(s) of event to which you want to restrict your search. See above for acceptable values. |
search[after] |
An ISO-8601 timestamp. Results will be filtered to events that took place after this time. |
search[before] |
An ISO-8601 timestamp. Results will be filtered to events that took place prior to this time. |
Response
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors": [
"The requested type (Other) is not supported."
]
}
Fields
Name | Description |
---|---|
errors |
A description of the error that prevented the search. |
Locations
View the location hierarchy for your account. Locations are structured with one root location attached directly to your account, and potentially multiple sublocations for every location.
[
{"id": 1, "name": "Account (Root)", "sublocation_ids": [2]},
{"id": 2, "name": "Warehouse", "sublocation_ids": []}
]
The following list might represent a simple location hierarchy for an organization monitoring a single warehouse:
- Account (Root) [1]
- Warehouse [2]
In order to reconstruct the full location hierarchy from the response, you
can start with the root location element (the first element in the list),
and follow the sublocation_ids
for that location, nesting the locations
with the specified IDs beneath the root. You can then repeat this process
for each sublocation, stopping when you reach a location with no
sublocation_ids
. Let’s look at an example for a slightly more complicated
organization.
[
{"id": 1, "name": "Account (Root)", "sublocation_ids": [2]},
{"id": 2, "name": "Region", "sublocation_ids": [3, 4]},
{"id": 3, "name": "Office #1", "sublocation_ids": []},
{"id": 4, "name": "Office #2", "sublocation_ids": []}
]
The following list might represent an organization with a deeper location hierarchy, due to a high density of sensors, or sensors used for multiple purposes or applications throughout the organization:
- Account (Root) [1]
- Region [2]
- Office #1 [3]
- Office #2 [4]
- Region [2]
As above, you can follow the sublocation_ids
starting with the root
location to reconstruct the proper hierarchy for your organization.
Listing account locations
Retrieve a list of locations belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/locations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/locations
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 44,
"name": "Kuphal and Sons",
"sublocation_ids": [
45,
46
],
"resource": "Location",
"relationships": {
}
},
{
"id": 45,
"name": "Bedroom 4",
"sublocation_ids": [
],
"resource": "Location",
"relationships": {
}
},
{
"id": 46,
"name": "Hallway 5",
"sublocation_ids": [
],
"resource": "Location",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
},
"devices": {
"meta": {
"count": 2
}
}
}
}
],
"meta": {
"pagination": {
"record_count": 3,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The locations’s unique identifier. |
name |
The location’s name. |
sublocation_ids |
A list of IDs for the locations nested beneath this one. |
Listing filtered locations
Retrieve a list of all locations for your account matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/locations?search[name]=Ruby+Office&search[ids][]=48&search[ids][]=49&search[ids][]=50 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/locations
Parameters
Name | Description |
---|---|
search[name] |
A partial name for locations to which you want to restrict your search. |
search[ids] |
A list of IDs for the locations to which you want to restrict your search. |
Fetching a specific location
By requesting details for a single location, you can see more information, including the device metadata for that location.
Request
GET /api/rest/locations/53 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/locations/:id
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 53,
"name": "Block Group",
"sublocation_ids": [
],
"resource": "Location",
"devices": [
{
"name": "Beverage opener 45",
"token": "544472574516050626",
"sku": "B000A3LPTC",
"serial": "af0f907a1d762ccf",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
},
{
"name": "Mangle (machine) 46",
"token": "937786718155853126",
"sku": "B0002XCH2E",
"serial": "1a5121468128f493",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
}
],
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
},
"devices": {
"meta": {
"count": 2
}
}
}
}
}
Fields
Name | Description |
---|---|
id |
The location’s unique identifier. |
name |
The location’s name. |
devices |
A list of devices attached to this location. |
sublocation_ids |
A list of IDs for the locations nested beneath this one. |
Searches
Search globally across the monitoring points for your account. Results are returned as an Array of objects, each listed with its resource type.
Metadata
Metadata includes pagination. For more information about interacting with paginated data, see Pagination.
{
"data": [
{
"id": 1,
"uuid": "2c619897-2fa5-4eaa-9bce-f18b4b34173b",
"name": "Temperature CH:1",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel"
},
{
"name": "Attic fan 1",
"token": "777297514715219033",
"sku": "B000GTFRX0",
"serial": "ca25e2294198245e",
"battery": null,
"is_replaced": false,
"resource": "Device"
},
{
"id": 2,
"name": "Drawing Room 1",
"sublocation_ids": [
],
"resource": "Location"
},
],
"meta": {
"pagination": {
"record_count": 10,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Listing search results
Globally search to find matches relating to device, channel, and/or location. This list is paginated by group. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/searches?search[query]=Office HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/searches
Parameters
Name | Description |
---|---|
search[query] |
A partial name that corresponds to a channel, device, or location. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 150,
"uuid": "adf2f798-8c3e-476e-96c0-bd5cc2b19ee5",
"name": "Office Door",
"type": "Boolean",
"unit": "boolean",
"first_datapoint_at": "2022-08-03T19:40:25.000Z",
"last_datapoint_at": "2022-09-07T19:36:25.000Z",
"resource": "Channel",
"summary_url": "http://localhost:4001/datapoints/adf2f798-8c3e-476e-96c0-bd5cc2b19ee5/1659555625/1662579385/summary",
"readings_urls": [
"http://localhost:4001/datapoints/adf2f798-8c3e-476e-96c0-bd5cc2b19ee5/1659555625/1662185370",
"http://localhost:4001/datapoints/adf2f798-8c3e-476e-96c0-bd5cc2b19ee5/1662185371/1662579385"
],
"device": {
"name": "Fridge",
"token": "348025745853205356",
"sku": "B000BJ4VFA",
"serial": "a3a9411c067a6e5c",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 2
}
}
}
},
"location": {
"id": 90,
"name": "Ruby Office",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
},
{
"name": "Office",
"token": "404962406029977755",
"sku": "B0000VAA8G",
"serial": "68a4a5d2a4996cbf",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"channels": [
],
"location": {
"id": 90,
"name": "Ruby Office",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"id": 90,
"name": "Ruby Office",
"sublocation_ids": [
],
"resource": "Location",
"devices": [
{
"name": "Fridge",
"token": "348025745853205356",
"sku": "B000BJ4VFA",
"serial": "a3a9411c067a6e5c",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 2
}
}
}
},
{
"name": "Office",
"token": "404962406029977755",
"sku": "B0000VAA8G",
"serial": "68a4a5d2a4996cbf",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
}
},
{
"name": "Garage",
"token": "716432056677473694",
"sku": "B000A3PI3G",
"serial": "5b3f668c198fbf9a",
"battery": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
}
],
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
},
"devices": {
"meta": {
"count": 3
}
}
}
},
{
"id": 91,
"name": "Elixir Office",
"sublocation_ids": [
],
"resource": "Location",
"devices": [
],
"relationships": {
}
}
],
"meta": {
"pagination": {
"record_count": 4,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
resource |
The resource type of the search result. One of |
Users
View and update the users that have access to your account.
Listing account users
Retrieve a list of users belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/users HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/users
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 51,
"email": "feeney_tim@sporer.net",
"full_name": "Tim Feeney",
"first_name": "Tim",
"last_name": "Feeney",
"current_login_at": "2022-09-16T17:46:04.000Z",
"last_login_at": "2022-09-15T18:46:04.000Z",
"last_request_at": "2022-09-16T18:46:04.000Z",
"time_zone": "Central Time (US & Canada)",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
{
"id": 52,
"email": "macgyver_vern@bogisich.name",
"full_name": "Vern MacGyver",
"first_name": "Vern",
"last_name": "MacGyver",
"current_login_at": "2022-09-16T17:46:04.000Z",
"last_login_at": "2022-09-09T18:46:04.000Z",
"last_request_at": "2022-09-16T18:41:04.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
{
"id": 53,
"email": "schiller.mimi@leffler-doyle.name",
"full_name": "Mimi Schiller",
"first_name": "Mimi",
"last_name": "Schiller",
"current_login_at": "2022-09-16T17:46:04.000Z",
"last_login_at": "2022-09-09T18:46:04.000Z",
"last_request_at": "2022-09-16T18:41:04.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
],
"meta": {
"pagination": {
"record_count": 3,
"page_size": 25,
"page_count": 1,
"current_page": 1,
"prev_page": null,
"next_page": null
}
}
}
Fields
Name | Description |
---|---|
id |
The user’s unique identifier. |
email |
The user’s email address. |
full_name |
The user’s full name. |
first_name |
The user’s first name. |
last_name |
The user’s last name. |
current_login_at |
The timestamp of the user’s current login to DicksonOne. |
last_login_at |
The timestamp of the user’s prior login to DicksonOne. |
last_request_at |
The timestamp of the user’s most recent request to DicksonOne. |
time_zone |
The user’s configured time zone. |
role |
The user’s assigned role in DicksonOne. |
locale |
The user’s configured language preference. |
datetime_format |
The user’s configured datetime preference. We return this in a MomentJS friendly
format. You can anticipate the following specific formats: |
Updating an existing user
The User’s contact attributes can be updated.
Request
PATCH /api/rest/users/61 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"user": {
"email": "rhoda_haley@wunsch.com",
"first_name": "Rhoda",
"last_name": "Haley",
"locale": "es"
}
}
Endpoint
PATCH /api/rest/users/:id
Parameters
Name | Description |
---|---|
user[email] |
The new email address for the user. |
user[first_name] |
The new first name for the user. |
user[last_name] |
The new last name for the user. |
user[locale] |
The new language option for the user. Accepted inputs for setting locale include: ‘en’ (English), ‘es’ (Spanish), or ‘fr’ (French). |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 61,
"email": "rhoda_haley@wunsch.com",
"full_name": "Rhoda Haley",
"first_name": "Rhoda",
"last_name": "Haley",
"current_login_at": "2022-09-16T17:46:07.000Z",
"last_login_at": "2022-09-14T18:46:07.000Z",
"last_request_at": "2022-09-16T18:41:07.000Z",
"time_zone": "Central Time (US & Canada)",
"role": null,
"locale": "es",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
}
Fields
Name | Description |
---|---|
id |
The user’s unique identifier. |
email |
The user’s updated email address. |
first_name |
The user’s updated first name. |
last_name |
The user’s updated last name. |
locale |
The user’s configured language preference. |
datetime_format |
The user’s configured datetime preference. We return this in a MomentJS friendly
format. You can anticipate the following specific formats: |
Updating with invalid attributes
Email addresses must be properly formatted, and no blank values are allowed. Attempting to set any of a user’s attributes to an invalid value will result in an error response.
Request
PATCH /api/rest/users/63 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"user": {
"email": "not.an.email",
"first_name": ""
}
}
Endpoint
PATCH /api/rest/users/:id
Parameters
Name | Description |
---|---|
user[email] |
The new email address for the user. |
user[first_name] |
The new first name for the user. |
user[last_name] |
The new last name for the user. |
user[locale] |
The new language option for the user. Accepted inputs for setting locale include: ‘en’ (English), ‘es’ (Spanish), or ‘fr’ (French). |
Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
{
"errors": [
"First name can't be blank"
]
}
Fields
Name | Description |
---|---|
errors |
A list of the errors that prevented the record from being updated. |
Returns information about the user performing the request
Retrieve a single record of the user that is logged in. This can be helpful in building a user profile. As long as the user has been properly authenticated, this route will tell you who they are.
Request
GET /api/rest/whoami HTTP/1.1
Authorization: Bearer YkAgpq7LKhsw94U-q8v6-hgER65Wx28xWCw4kVg_Xuc
Content-Type: application/json
Endpoint
GET /api/rest/whoami