NAV
HTTP

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

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

Code Description
200 The request was successful.
201 A record was created in response to the request.

Error Codes

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 warning or excursion.

type

The type of alert. Either not_reporting or high_low.

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 false (default) or true.

search[severity]

The severity of alerts to which you want to restrict your search. Acceptable values are all (default), excursion, or warning.

search[type]

The type of alerts to which you want to restrict your search. Acceptable values are all (default), not_reporting, or high_low.

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 warning or excursion.

type

The type of alert. Either not_reporting or high_low.

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 all (default), excursion, or warning.

search[type]

The type of alerts to which you want to restrict your search. Acceptable values are all (default), not_reporting, or high_low.

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 warning or excursion.

type

The type of alert. Either not_reporting or high_low.

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:

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:

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 Channel, Device, or Location.

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: MM/DD/YYYY h:mm:ss TT, YYYY-MM-DD HH:mm:ss, YYYY-MM-DD h:mm:ssTT, MM/DD/YYYY HH:mm:ss, DD/MM/YYYY HH:mm:ss, or DD/MM/YYYY h:mm:ssTT.

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: MM/DD/YYYY h:mm:ss TT, YYYY-MM-DD HH:mm:ss, YYYY-MM-DD h:mm:ssTT, MM/DD/YYYY HH:mm:ss, DD/MM/YYYY HH:mm:ss, or DD/MM/YYYY h:mm:ssTT.

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