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

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

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.

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.

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

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

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

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

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

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "active": 1,
    "cleared": 1,
    "excursion": 0,
    "warning": 2
  },
  "meta": {
  }
}

Fields

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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