API Reference
The DicksonOne REST API uses predictable resource-oriented URLs, accepts both JSON-encoded and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Please Note
- If you’re maintaining an integration for the previous version (V2) of this API, you can find that documentation here. The V2 API will be deprecated at some point in the future, so we encourage you to move your integration to the new REST API.
- This code is provided “AS IS” without warranty of any kind expressed or implied. Dickson does not provide support for custom integrations.
- We’re in the process of updating our REST API responses to model JSON:API specification. You may see some objects that follow the pattern specification as detailed in the Document Structure.
Base URL
Code examples below assume that requests are being directed to endpoints for the application at a base URL. All listed request endpoints should be directed to the following domain:
https://www.dicksonone.com
Authentication
GET https://www.dicksonone.com/api/rest/users HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
The DicksonOne API uses API keys to authenticate requests. Account Managers and Owners can manage the API keys available for their account via “Manage > API Keys”. Use of this API requires that your account have an active subscription with an appropriate level of features. If you’re interested in accessing the REST API and don’t currently have access to API Key management, please contact support@dicksonone.com to discuss upgrading your subscription.
In order to access the API, you’ll need to pass the token associated with an active API Key as a Bearer token in the Authorization header for each request.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Pagination
Due to the large number of records that can be returned with each request, DicksonOne’s REST API uses pagination to pass back records in manageable chunks.
Request
GET https://www.dicksonone.com/api/rest/locations?page[number]=2&page[size]=3 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
For API endpoints that return a collection of results, you can control which page of results you’re fetching, as well as the number of results included on each page, using the following pagination parameters.
Parameters
| Name | Description |
|---|---|
| page[number] | The number of the page you’re requesting. |
| page[size] | The number of results you want to receive per-page. This defaults to 25, and has a maximum value of 100. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{ "id": 4, "name": "Pharmaceutical Warehouse - West", "sublocation_ids": [5, 6] },
{ "id": 5, "name": "Vaccine Refrigerator A", "sublocation_ids": [] },
{ "id": 6, "name": "Vaccine Refrigerator B", "sublocation_ids": [] }
],
"meta" : {
"pagination": {
"record_count": 7,
"page_size": 3,
"page_count": 3,
"current_page": 2,
"prev_page": 1,
"next_page": 3
}
}
}
Each response for a paginated endpoint will include a set of metadata for the paginated results, in addition to the list of record data.
Fields
| Name | Description |
|---|---|
| data | The list of record data for the current page of results. |
| meta[pagination][record_count] | The total count of records in the collection. |
| meta[pagination][page_size] | The number of results included per-page. |
| meta[pagination][page_count] | The total number of results pages. |
| meta[pagination][current_page] | The number of the current page of results. |
| meta[pagination][prev_page] | The number of the previous page of results. |
| meta[pagination][next_page] | The number of the next page of results. |
Errors
DicksonOne uses conventional HTTP response codes to indicate the success or failure of an API request.
Success Codes
- Codes in the 2xx range indicate a successful response.
| Code | Description |
|---|---|
| 200 | The request was successful. |
| 201 | A record was created in response to the request. |
Error Codes
- Codes in the 3xx range indicate that the request needs to be redirected.
- Codes in the 4xx range indicate that the content or structure of the request is invalid (e.g., a missing or blank parameter).
- Codes in the 5xx range indicate an error on DicksonOne’s servers.
| Code | Description |
|---|---|
| 301 | The request was made via HTTP, rather than HTTPS. You will need to attempt your request again using SSL. |
| 400 | The request’s format was invalid. This can be triggered by invalid pagination parameters. |
| 401 | No API token was supplied, or the supplied API token was invalid. |
| 403 | The user authenticated by the API token is not permitted to perform the requested action. |
| 404 | The requested record wasn’t found. |
| 409 | Your request caused a conflict with existing data. Review the list of error messages to determine how to resolve the error. |
| 422 | The requested change was rejected due to validation errors. Review the list of error messages to determine how to resolve the error. |
| 500 | A hard-error occurred on DicksonOne’s servers. If the problem persists, please report the issue to support@dicksonone.com, with as much detail as possible. |
| 503 | DicksonOne is experiencing a service outage. You can try your request again in a few moments. |
Support
Dickson does not provide support for custom integrations. If you have general questions regarding access to or the functionality of the API, please email support@dicksonone.com. This code is provided “as is”, without warranty of any kind expressed or implied.
Data Loggers
View the data loggers configured for your account. Each record represents
the current status of a particular environmental logger. Instead of integer
IDs, loggers are thus accessed using a string token, which is maintained
across logger hardware replacements.
Listing data loggers by location
Retrieve a list of the data loggers attached to a specific location. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/locations/2/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": "Drawer dishwasher 1",
"token": "350811522551436413",
"sku": "B000ALJYO2",
"serial": "bdaad7511f83a319",
"battery": 4.0,
"firmware": "0.1.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 2,
"name": "Sunroom 1",
"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 loggers’s unique identifier. This value is maintained across logger replacements. |
|
name |
The logger’s name. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
battery |
The logger’s current battery level, represented as an integer between 0 and 5. Only present for supported devices. |
Listing annotations for a data logger
Retrieve a list of all annotations added to channels on a specific data logger. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices/635145408168665227/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": "Cum aperiam nemo. Sit quam aut.",
"at": "2024-01-02T16:36:55.000Z",
"channel": {
"id": 1,
"uuid": "bba6d95f-7412-4489-8aa6-77cda2de6362",
"name": "Temperature CH:1",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"sensor": null
},
"user": {
"id": 3,
"account_id": 3,
"email": "braun_thu@hartmann.example",
"full_name": "Thu Braun",
"first_name": "Thu",
"last_name": "Braun",
"current_login_at": "2024-02-02T15:36:55.000Z",
"last_login_at": "2024-02-01T16:36:55.000Z",
"last_request_at": "2024-02-02T16:31:55.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
},
{
"id": 2,
"content": "Vel repudiandae nemo. Qui atque aut.",
"at": "2024-01-19T16:36:55.000Z",
"channel": {
"id": 2,
"uuid": "28be1f3b-8e87-482d-8224-b9aa972ecefb",
"name": "Temperature CH:2",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"sensor": null
},
"user": {
"id": 4,
"account_id": 4,
"email": "hessel_sanora@kuhic-schneider.test",
"full_name": "Sanora Hessel",
"first_name": "Sanora",
"last_name": "Hessel",
"current_login_at": "2024-02-02T15:36:55.000Z",
"last_login_at": "2024-02-01T16:36:55.000Z",
"last_request_at": "2024-02-02T16:31:55.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
}
],
"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 data logger annotations
Retrieve a list of annotations for the data logger matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices/883197752425115374/annotations?search[after]=2023-12-29T16%3A36%3A56Z&search[before]=2024-01-12T16%3A36%3A56Z 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": 3,
"content": "Et alias est. Molestias est culpa.",
"at": "2024-01-02T16:36:56.000Z",
"channel": {
"id": 5,
"uuid": "07e1fbb2-359d-4851-a23d-6f3aed81c6f9",
"name": "Temperature CH:5",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"sensor": null
},
"user": {
"id": 6,
"account_id": 6,
"email": "heidenreich_irmgard@white-sanford.example",
"full_name": "Irmgard Heidenreich",
"first_name": "Irmgard",
"last_name": "Heidenreich",
"current_login_at": "2024-02-02T15:36:56.000Z",
"last_login_at": "2024-02-01T16:36:56.000Z",
"last_request_at": "2024-02-02T16:31:56.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
}
],
"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. |
Listing account data loggers
Retrieve a list of all data loggers belonging to your account. Does not include archived or replaced loggers. 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": "Gas appliance 4",
"token": "114611532048804842",
"sku": "B000AR99QO",
"serial": "1ba05acba2db1b02",
"battery": 2.0,
"firmware": "0.4.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 9,
"name": "Lebsack Inc",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Radiator (heating) 5",
"token": "904612630398856661",
"sku": "B000AR85S2",
"serial": "b0afd3180f4c1280",
"battery": 2.0,
"firmware": "0.5.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 9,
"name": "Lebsack Inc",
"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 |
|---|---|
|
name |
The logger’s name. |
|
token |
The logger’s unique identifier. This value is maintained across logger replacements. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
battery |
The logger’s current battery level, represented as an integer between 0 and 5. Only present for supported loggers. |
|
firmware |
The current version of the logger’s firmware. |
|
last_datapoint_at |
The date and time at which the logger last captured an environmental reading. |
|
last_reported_at |
The date and time at which DicksonOne last received a reading from the logger. |
|
is_replaced |
A boolean indicating whether or not the logger has been replaced. |
|
archived_at |
A date indicating if and when the logger was archived. |
|
location |
The location where this logger is being used. |
Listing archived data loggers
Retrieve a list of all data loggers belonging to your account, including loggers that have been archived. This list is paginated.
Request
GET /api/rest/devices?search[include_archived]=true HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices
Parameters
| Name | Description |
|---|---|
| search[include_archived] |
A boolean. Results will be filtered to include archived loggers if true. Defaults to false. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"name": "Micathermic heater 10",
"token": "718517057440666337",
"sku": "B00069TDVW",
"serial": "7c2df92a9898b485",
"battery": 2.0,
"firmware": "0.10.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 10,
"name": "Wolf-Ullrich",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Water purifier 11",
"token": "792822424913753538",
"sku": "B000A2LQ2O",
"serial": "a3bfc1dc662aac5a",
"battery": 2.0,
"firmware": "0.11.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 10,
"name": "Wolf-Ullrich",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Window fan 12",
"token": "718517057440666337",
"sku": "B0009QMECC",
"serial": "01183526d801153e",
"battery": null,
"firmware": "0.12.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": "2024-02-02T15:36:58.000Z",
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 10,
"name": "Wolf-Ullrich",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Toaster and toaster ovens 13",
"token": "718517057440666337",
"sku": "B0007WHCXO",
"serial": "6c7e1475518f5c80",
"battery": null,
"firmware": "0.13.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": "2024-02-02T15:36:58.000Z",
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 10,
"name": "Wolf-Ullrich",
"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 |
|---|---|
|
name |
The logger’s name. |
|
token |
The logger’s unique identifier. This value is maintained across logger replacements. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
battery |
The logger’s current battery level, represented as an integer between 0 and 5. Only present for supported loggers. |
|
firmware |
The current version of the logger’s firmware. |
|
last_datapoint_at |
The date and time at which the logger last captured an environmental reading. |
|
last_reported_at |
The date and time at which DicksonOne last received a reading from the logger. |
|
is_replaced |
A boolean indicating whether or not the logger has been replaced. |
|
archived_at |
A date indicating if and when the logger was archived. |
|
location |
The location where this logger is being used. |
Listing replaced data loggers
Retrieve a list of all data loggers belonging to your account, including older logger 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 loggers if true. Defaults to false. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"name": "Futon dryer 16",
"token": "745219509204875927",
"sku": "B000A6Y8AW",
"serial": "b10d1369a406e563",
"battery": 2.0,
"firmware": "0.16.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 11,
"name": "Dibbert, Muller and Mraz",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Radiator (heating) 17",
"token": "464036670718651525",
"sku": "B000A3LC18",
"serial": "909ae5aa70093627",
"battery": 2.0,
"firmware": "0.17.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 11,
"name": "Dibbert, Muller and Mraz",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Water purifier 20",
"token": "745219509204875927",
"sku": "B000H3HHOM",
"serial": "6244152e7dfd0367",
"battery": null,
"firmware": "0.20.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": true,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 11,
"name": "Dibbert, Muller and Mraz",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"name": "Box mangle 21",
"token": "745219509204875927",
"sku": "B00067668W",
"serial": "819be36402c89fcf",
"battery": null,
"firmware": "0.21.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": true,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 11,
"name": "Dibbert, Muller and Mraz",
"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 |
|---|---|
|
name |
The logger’s name. |
|
token |
The logger’s unique identifier. This value is maintained across logger replacements. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
battery |
The logger’s current battery level, represented as an integer between 0 and 5. Only present for supported loggers. |
|
firmware |
The current version of the logger’s firmware. |
|
last_datapoint_at |
The date and time at which the logger last captured an environmental reading. |
|
last_reported_at |
The date and time at which DicksonOne last received a reading from the logger. |
|
is_replaced |
A boolean indicating whether or not the logger has been replaced. |
|
archived_at |
A date indicating if and when the logger was archived. |
|
location |
The location where this logger is being used. |
Listing data loggers filtered by name
Retrieve a list of all loggers for your account matching the specified service name. 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 loggers 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": "535106133912410195",
"sku": "B000HU7P92",
"serial": "c955e9c10cd0b56a",
"battery": 2.0,
"firmware": "0.22.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 12,
"name": "Kling Inc",
"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 |
|---|---|
|
name |
The logger’s name. |
|
token |
The logger’s unique identifier. This value is maintained across logger replacements. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
battery |
The logger’s current battery level, represented as an integer between 0 and 5. Only present for supported loggers. |
|
firmware |
The current version of the logger’s firmware. |
|
last_datapoint_at |
The date and time at which the logger last captured an environmental reading. |
|
last_reported_at |
The date and time at which DicksonOne last received a reading from the logger. |
|
is_replaced |
A boolean indicating whether or not the logger has been replaced. |
|
archived_at |
A date indicating if and when the logger was archived. |
|
location |
The location where this logger is being used. |
Listing data loggers filtered by service name
Retrieve a list of all loggers for your account matching the specified service name. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices?search[service_name]=dicksonone.com HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices
Parameters
| Name | Description |
|---|---|
| search[service_name] |
The name of the service that registered the loggers you want to restrict your search to. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"name": "Beverage opener 27",
"token": "827925136541761618",
"sku": "B000B7CC94",
"serial": "bf329cdc13089570",
"battery": 2.0,
"firmware": "0.30.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"location": {
"id": 13,
"name": "Wilderman Inc",
"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 |
|---|---|
|
name |
The logger’s name. |
|
token |
The logger’s unique identifier. This value is maintained across logger replacements. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
battery |
The logger’s current battery level, represented as an integer between 0 and 5. Only present for supported loggers. |
|
firmware |
The current version of the logger’s firmware. |
|
last_datapoint_at |
The date and time at which the logger last captured an environmental reading. |
|
last_reported_at |
The date and time at which DicksonOne last received a reading from the logger. |
|
is_replaced |
A boolean indicating whether or not the logger has been replaced. |
|
archived_at |
A date indicating if and when the logger was archived. |
|
location |
The location where this logger is being used. |
Fetching a specific data logger
By requesting details for a single data logger, you can see more information, including the channel metadata for that logger.
Request
GET /api/rest/devices/710936275362745493 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": "Fan heater 35",
"token": "710936275362745493",
"sku": "B000BNLKWS",
"serial": "30a41eb0760b54cf",
"battery": 3.0,
"firmware": "0.38.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 2
}
}
},
"channels": [
{
"id": 11,
"uuid": "f8cfba3d-8d86-4ae3-b18e-83d9b3c77659",
"name": "Temperature CH:11",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-01-12T16:37:01.000Z",
"last_datapoint_at": "2024-02-02T16:23:01.000Z",
"resource": "Channel",
"sensor": null
},
{
"id": 12,
"uuid": "d90d8c72-1bec-480f-99e8-487fd1261262",
"name": "Temperature CH:12",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-01-26T16:37:01.000Z",
"last_datapoint_at": "2024-02-02T16:23:01.000Z",
"resource": "Channel",
"sensor": null
}
],
"location": {
"id": 18,
"name": "Feil, Turner and Padberg",
"sublocation_ids": [
],
"resource": "Location"
}
}
}Fields
| Name | Description |
|---|---|
|
token |
The logger’s unique identifier. This value is maintained across logger replacements. |
|
name |
The logger’s name. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
battery |
The logger’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 logger. |
|
location |
The location where this logger is being used. |
Users
View and update the users that have access to your account.
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/17 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": [
{
"status": "422",
"title": "Validation Error",
"detail": "First name can't be blank",
"source": {
"pointer": "/data/attributes/first_name"
},
"meta": {
"attribute": "first_name",
"code": "blank",
"message": "can't be blank"
}
}
]
}Fields
| Name | Description |
|---|---|
|
errors |
A list of the errors that prevented the record from being updated. |
Updating an existing user
The User’s contact attributes can be updated.
Request
PATCH /api/rest/users/19 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"user": {
"email": "o_richelle_hara@padberg-schaefer.test",
"first_name": "Richelle",
"last_name": "O'Hara",
"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": 19,
"account_id": 17,
"email": "o_richelle_hara@padberg-schaefer.test",
"full_name": "Richelle O'Hara",
"first_name": "Richelle",
"last_name": "O'Hara",
"current_login_at": "2024-02-02T15:37:03.000Z",
"last_login_at": "2024-01-31T16:37:03.000Z",
"last_request_at": "2024-02-02T16:32:03.000Z",
"time_zone": "America/Chicago",
"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: |
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": 20,
"account_id": 18,
"email": "joaquin.muller@labadie.example",
"full_name": "Joaquin Muller",
"first_name": "Joaquin",
"last_name": "Muller",
"current_login_at": "2024-02-02T15:37:03.000Z",
"last_login_at": "2024-02-01T16:37:03.000Z",
"last_request_at": "2024-02-02T16:37:04.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
{
"id": 21,
"account_id": 18,
"email": "conner.jesse.o@marvin.test",
"full_name": "Jesse O'Conner",
"first_name": "Jesse",
"last_name": "O'Conner",
"current_login_at": "2024-02-02T15:37:03.000Z",
"last_login_at": "2024-01-26T16:37:03.000Z",
"last_request_at": "2024-02-02T16:32:03.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
{
"id": 22,
"account_id": 18,
"email": "will_mitchell@greenfelder.test",
"full_name": "Will Mitchell",
"first_name": "Will",
"last_name": "Mitchell",
"current_login_at": "2024-02-02T15:37:04.000Z",
"last_login_at": "2024-01-26T16:37:03.000Z",
"last_request_at": "2024-02-02T16:32:04.000Z",
"time_zone": "America/Chicago",
"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. |
|
account_id |
The unique identifier for the account to which the user belongs. |
|
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: |
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 RtMZRGnDHtQwEi1S2MaOQ8O3h4v56-UGASE82ozRXCU
Content-Type: application/json
Endpoint
GET /api/rest/whoami
Override Windows
Define logger configurations for the duration of an ongoing study.
Listing override windows for a device
Lists all override windows for the specified device.
Request
GET /api/rest/devices/205183531497687498/overrides HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices/:token/overrides
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 1,
"token": "205183531497687498",
"start_time": "2024-02-03T16:37:09.287Z",
"end_time": "2024-02-04T16:37:09.287Z",
"settings": {
"temperature_display_unit": "celsius",
"time_zone": "Central Time (US & Canada)"
}
}
]
}Fields
| Name | Description |
|---|---|
|
id |
The override window identifier. |
|
token |
The logger’s token. |
|
start_time |
The start of the override window. |
|
end_time |
The end of the override window. |
|
settings |
The settings to be overridden during the window. |
Creating an override window
Creates a new override window for the data logger.
Request
POST /api/rest/devices/281405613251666151/overrides HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"override": {
"start_time": "2024-02-03T16:37:09Z",
"end_time": "2024-02-04T16:37:09Z",
"settings": {
"device_name": "A001",
"temperature_display_unit": "celsius",
"time_zone": "Central Time (US & Canada)"
}
}
}Endpoint
POST /api/rest/devices/:token/overrides
Parameters
| Name | Description |
|---|---|
| override[start_time] |
The start of the override window. |
| override[end_time] |
The end of the override window. |
| override[settings] |
The settings to be overridden during the window. |
Response
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 2,
"token": "281405613251666151",
"start_time": "2024-02-03T16:37:09.000Z",
"end_time": "2024-02-04T16:37:09.000Z",
"settings": {
"temperature_display_unit": "celsius",
"time_zone": "Central Time (US & Canada)",
"device_name": "A001"
}
}
}Fields
| Name | Description |
|---|---|
|
id |
The override window identifier. |
|
token |
The logger’s token. |
|
start_time |
The start of the override window. |
|
end_time |
The end of the override window. |
|
settings |
The settings to be overridden during the window. |
Creating an override window with invalid attributes
The new override window cannot overlap with any existing override windows for the same device.
Request
POST /api/rest/devices/583875519404348752/overrides HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"override": {
"start_time": "2024-02-03T16:37:10Z",
"end_time": "2024-02-04T16:37:10Z",
"settings": {
"device_name": "A001",
"temperature_display_unit": "celsius",
"time_zone": "Central Time (US & Canada)"
}
}
}Endpoint
POST /api/rest/devices/:token/overrides
Parameters
| Name | Description |
|---|---|
| override[start_time] |
The start of the override window. |
| override[end_time] |
The end of the override window. |
| override[settings] |
The settings to be overridden during the window. |
Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
{
"errors": [
{
"status": "422",
"title": "Validation Error",
"detail": "Must not overlap with another window",
"source": {
"pointer": "/data/attributes/base"
},
"meta": {
"attribute": "base",
"code": "window_overlap",
"message": "Must not overlap with another window"
}
}
]
}Fields
| Name | Description |
|---|---|
|
errors |
A list of the errors that prevented the override window from being created. |
Updating an override window with invalid attributes
An override window cannot overlap with any existing override windows for the logger. All supplied settings for an override window are additionally validated for conformity with supported values.
Request
PATCH /api/rest/devices/529289907574176287/overrides/4 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"override": {
"start_time": "2024-02-05T16:37:10Z",
"end_time": "2024-02-07T16:37:10Z",
"settings": {
"pressure_display_unit": "N/m2"
}
}
}Endpoint
PATCH /api/rest/devices/:token/overrides/:id
Parameters
| Name | Description |
|---|---|
| override[start_time] |
The start of the override window. |
| override[end_time] |
The end of the override window. |
| override[settings] |
The settings to be overridden during the window. |
Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
{
"errors": [
{
"status": "422",
"title": "Validation Error",
"detail": "Must not overlap with another window",
"source": {
"pointer": "/data/attributes/base"
},
"meta": {
"attribute": "base",
"code": "window_overlap",
"message": "Must not overlap with another window"
}
},
{
"status": "422",
"title": "Validation Error",
"detail": "Pressure display unit is not included in the list",
"source": {
"pointer": "/data/attributes/pressure_display_unit"
},
"meta": {
"attribute": "pressure_display_unit",
"code": "inclusion",
"message": "is not included in the list"
}
}
]
}Fields
| Name | Description |
|---|---|
|
errors |
A list of the errors that prevented the override window from being updated. |
Updating an override window
Updates the specified override window.
Request
PATCH /api/rest/devices/163837177213993836/overrides/6 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"override": {
"start_time": "2024-02-05T16:37:11Z",
"end_time": "2024-02-07T16:37:11Z",
"settings": {
"device_name": "A001",
"temperature_display_unit": "fahrenheit",
"time_zone": "Central Time (US & Canada)"
}
}
}Endpoint
PATCH /api/rest/devices/:token/overrides/:id
Parameters
| Name | Description |
|---|---|
| override[start_time] |
The start of the override window. |
| override[end_time] |
The end of the override window. |
| override[settings] |
The settings to be overridden during the window. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 6,
"token": "163837177213993836",
"start_time": "2024-02-05T16:37:11.000Z",
"end_time": "2024-02-07T16:37:11.000Z",
"settings": {
"temperature_display_unit": "fahrenheit",
"time_zone": "Central Time (US & Canada)",
"device_name": "A001"
}
}
}Fields
| Name | Description |
|---|---|
|
id |
The override window identifier. |
|
token |
The logger’s token. |
|
start_time |
The start of the override window. |
|
end_time |
The end of the override window. |
|
settings |
The settings to be overridden during the window. |
Showing an override window
Shows the specified override window.
Request
GET /api/rest/devices/427346494795659880/overrides/7 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/devices/:token/overrides/:id
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"id": 7,
"token": "427346494795659880",
"start_time": "2024-02-03T16:37:11.528Z",
"end_time": "2024-02-04T16:37:11.528Z",
"settings": {
"temperature_display_unit": "celsius",
"time_zone": "Central Time (US & Canada)"
}
}
}Fields
| Name | Description |
|---|---|
|
id |
The override window identifier. |
|
token |
The logger’s token. |
|
start_time |
The start of the override window. |
|
end_time |
The end of the override window. |
|
settings |
The settings to be overridden during the window. |
Deleting an override window
Deletes the specified override window.
Request
DELETE /api/rest/devices/592881342407024892/overrides/8 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
DELETE /api/rest/devices/:token/overrides/:id
Services
Check if a user has access to a specific service within their account.
Denied access to a service
When the the user making the request to the API does not have permission to access the relevant service location, the API will respond with a 403 Forbidden error.
Request
POST /api/rest/services HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"service": {
"name": "External Testing Service",
"url": "test.dicksonone.com"
}
}Endpoint
POST /api/rest/services
Parameters
| Name | Description |
|---|---|
| service[name] |
The name of the service. This will be assigned to the service location. |
| service[url] |
A unique identifier for the service. |
Confirming access to a service
Confirm that the user making the request has access to the service described in the submitted metadata.
Request
POST /api/rest/services HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"service": {
"name": "External Testing Service",
"url": "test.dicksonone.com"
}
}Endpoint
POST /api/rest/services
Parameters
| Name | Description |
|---|---|
| service[name] |
The name of the service. This will be assigned to the service location. |
| service[url] |
A unique identifier for the service. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"name": "External Testing Service",
"url": "test.dicksonone.com",
"location_id": 34
}
}Fields
| Name | Description |
|---|---|
|
name |
The current name of the service location. |
|
url |
The unique identifier for the service. |
|
location_id |
The ID of the location the service is registered against. |
Alerts
View the alerts that have been triggered by data loggers on your account. Each Alert record represents a historical event that was caused by a logger tripping the warning or excursion condition for a configured Alarm.
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/4/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": "Voluptatem hic cum. Eligendi eaque temporibus.",
"created_at": "2024-02-02T16:37:13.000Z",
"user": {
"id": 40,
"account_id": 31,
"email": "boyer.dawn@boyer.example",
"full_name": "Dawn Boyer",
"first_name": "Dawn",
"last_name": "Boyer",
"current_login_at": "2024-02-02T15:37:13.000Z",
"last_login_at": "2024-02-01T16:37:13.000Z",
"last_request_at": "2024-02-02T16:32:13.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
},
{
"id": 2,
"text": "Quo praesentium distinctio. Cumque maxime sed.",
"created_at": "2024-02-02T16:37:13.000Z",
"user": {
"id": 40,
"account_id": 31,
"email": "boyer.dawn@boyer.example",
"full_name": "Dawn Boyer",
"first_name": "Dawn",
"last_name": "Boyer",
"current_login_at": "2024-02-02T15:37:13.000Z",
"last_login_at": "2024-02-01T16:37:13.000Z",
"last_request_at": "2024-02-02T16:32:13.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
},
{
"id": 3,
"text": "Magnam facilis ea. Quo qui aut.",
"created_at": "2024-02-02T16:37:13.000Z",
"user": {
"id": 40,
"account_id": 31,
"email": "boyer.dawn@boyer.example",
"full_name": "Dawn Boyer",
"first_name": "Dawn",
"last_name": "Boyer",
"current_login_at": "2024-02-02T15:37:13.000Z",
"last_login_at": "2024-02-01T16:37:13.000Z",
"last_request_at": "2024-02-02T16:32:13.000Z",
"time_zone": "America/Chicago",
"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 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. |
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/5/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": 5,
"description": "Temperature CH:14 is above 10.0°F",
"type": "high_low",
"escalation_started_at": "2024-02-02T15:07:14.000Z",
"entered_at": "2024-02-02T15:37:14.000Z",
"excursion_at": "2024-02-02T16:07:14.000Z",
"returned_to_normal_at": null,
"acknowledged_at": "2024-02-02T16:37:14.000Z",
"relationships": {
"comments": {
"data": [
{
"type": "comment",
"id": "4"
}
],
"meta": {
"count": 1
}
}
},
"severity": "excursion",
"acknowledger": {
"id": 41,
"account_id": 33,
"email": "rupert_christiansen@mcclure.test",
"full_name": "Rupert Christiansen",
"first_name": "Rupert",
"last_name": "Christiansen",
"current_login_at": "2024-02-02T15:37:14.000Z",
"last_login_at": "2024-02-01T16:37:14.000Z",
"last_request_at": "2024-02-02T16:37:14.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
"location": {
"id": 37,
"name": "Wolf, Kilback and Johnson",
"sublocation_ids": [
],
"resource": "Location"
},
"device": {
"name": "Beverage opener 45",
"token": "110359701660780068",
"sku": "B00019774M",
"serial": "866584892bffc31d",
"battery": null,
"firmware": "0.48.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "5"
}
],
"meta": {
"count": 1
}
},
"channels": {
"meta": {
"count": 1
}
}
}
},
"channel": {
"id": 14,
"uuid": "65c0e56b-a3a1-47bd-861a-5309cc14934b",
"name": "Temperature CH:14",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-02-02T16:37:14.000Z",
"last_datapoint_at": "2024-02-02T16:35:14.000Z",
"resource": "Channel",
"sensor": null
}
}
}Fields
| Name | Description |
|---|---|
|
id |
The unique identifier for this Alert record. |
|
description |
The condition which resulted in the alert. |
|
severity |
The severity of alert. Either |
|
type |
The type of alert. Either |
|
escalation_started_at |
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert. |
|
entered_at |
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert. |
|
excursion_at |
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion. |
|
returned_to_normal_at |
An ISO-8601 timestamp representing the time that the alert was resolved. |
|
acknowledged_at |
An ISO-8601 timestamp representing the time that the alert was acknowledged. |
|
acknowledger |
The data for the user that acknowledged the alert. |
|
location |
The data for the location in which this alert took place. |
|
device |
The data for the data logger related to this alert. |
|
channel |
The data for the channel related to this alert. This will be null for logger-level (not reporting) alerts. |
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/6/comments HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"comment": {
"text": "Est ea omnis. Officiis sed voluptas. Dolores commodi eveniet."
}
}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": 5,
"text": "Est ea omnis. Officiis sed voluptas. Dolores commodi eveniet.",
"created_at": "2024-02-02T16:37:15.000Z",
"user": {
"id": 42,
"account_id": 34,
"email": "luci_heathcote@larson.example",
"full_name": "Luci Heathcote",
"first_name": "Luci",
"last_name": "Heathcote",
"current_login_at": "2024-02-02T15:37:14.000Z",
"last_login_at": "2024-02-01T16:37:14.000Z",
"last_request_at": "2024-02-02T16:37:15.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
}
}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. |
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": 7,
"description": "Temperature CH:16 is above 28.0°F",
"type": "high_low",
"escalation_started_at": "2024-02-02T15:07:15.000Z",
"entered_at": "2024-02-02T15:37:15.000Z",
"excursion_at": "2024-02-02T16:07:15.000Z",
"returned_to_normal_at": null,
"acknowledged_at": "2024-02-02T15:52:15.000Z",
"relationships": {
"comments": {
"data": [
],
"meta": {
"count": 0
}
}
},
"severity": "excursion",
"acknowledger": {
"id": 44,
"account_id": 36,
"email": "konopelski.justin@schaden.test",
"full_name": "Justin Konopelski",
"first_name": "Justin",
"last_name": "Konopelski",
"current_login_at": "2024-02-02T15:37:15.000Z",
"last_login_at": "2024-02-02T14:37:15.000Z",
"last_request_at": "2024-02-02T16:32:15.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
"location": {
"id": 40,
"name": "Beier-Carroll",
"sublocation_ids": [
],
"resource": "Location"
},
"device": {
"name": "Vacuum cleaner 48",
"token": "735729542523644928",
"sku": "B000N5FYOE",
"serial": "2dfe589bacc82a1d",
"battery": null,
"firmware": "0.51.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "7"
}
],
"meta": {
"count": 1
}
},
"channels": {
"meta": {
"count": 1
}
}
}
},
"channel": {
"id": 16,
"uuid": "a10ace40-9690-4eb2-9f1c-42dd0f8117de",
"name": "Temperature CH:16",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-01-19T16:37:15.000Z",
"last_datapoint_at": "2024-02-02T16:19:15.000Z",
"resource": "Channel",
"sensor": null
}
},
{
"id": 8,
"description": "Temperature CH:16 is above 28.0°F",
"type": "high_low",
"escalation_started_at": "2024-02-02T14:37:15.000Z",
"entered_at": "2024-02-02T15:07:15.000Z",
"excursion_at": null,
"returned_to_normal_at": "2024-02-02T15:37:15.000Z",
"acknowledged_at": null,
"relationships": {
"comments": {
"data": [
],
"meta": {
"count": 0
}
}
},
"severity": "warning",
"acknowledger": null,
"location": {
"id": 40,
"name": "Beier-Carroll",
"sublocation_ids": [
],
"resource": "Location"
},
"device": {
"name": "Vacuum cleaner 48",
"token": "735729542523644928",
"sku": "B000N5FYOE",
"serial": "2dfe589bacc82a1d",
"battery": null,
"firmware": "0.51.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "7"
}
],
"meta": {
"count": 1
}
},
"channels": {
"meta": {
"count": 1
}
}
}
},
"channel": {
"id": 16,
"uuid": "a10ace40-9690-4eb2-9f1c-42dd0f8117de",
"name": "Temperature CH:16",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-01-19T16:37:15.000Z",
"last_datapoint_at": "2024-02-02T16:19:15.000Z",
"resource": "Channel",
"sensor": 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 Alert record. |
|
description |
The condition which resulted in the alert. |
|
severity |
The severity of alert. Either |
|
type |
The type of alert. Either |
|
escalation_started_at |
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert. |
|
entered_at |
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert. |
|
excursion_at |
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion. |
|
returned_to_normal_at |
An ISO-8601 timestamp representing the time that the alert was resolved. |
|
acknowledged_at |
An ISO-8601 timestamp representing the time that the alert was acknowledged. |
|
acknowledger |
The data for the user that acknowledged the alert. |
|
location |
The data for the location in which this alert took place. |
|
device |
The data for the data logger related to this alert. |
|
channel |
The data for the channel related to this alert. This will be null for logger-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][]=791336753169654301&search[severity]=excursion&search[started_after]=2024-02-02T13%3A37%3A17Z 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 data loggers to which you want to restrict your search. |
| search[channel_ids] |
A list of IDs for the channels to which you want to restrict your search. |
| search[location_ids] |
A list of IDs for the locations to which you want to restrict your search. |
| search[active] |
Whether to specifically include only active alerts or not. Acceptable values are |
| search[severity] |
The severity of alerts to which you want to restrict your search. Acceptable values are |
| search[type] |
The type of alerts to which you want to restrict your search. Acceptable values are |
| search[started_after] |
An ISO-8601 timestamp. Results will be filtered to alerts triggered after this time. |
| search[started_before] |
An ISO-8601 timestamp. Results will be filtered to alerts triggered prior to this time. |
| search[ended_after] |
An ISO-8601 timestamp. Results will be filtered to alerts resolved after this time. |
| search[ended_before] |
An ISO-8601 timestamp. Results will be filtered to alerts resolved prior to this time. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 11,
"description": "Temperature CH:18 is above 65.0°F",
"type": "high_low",
"escalation_started_at": "2024-02-02T15:07:17.000Z",
"entered_at": "2024-02-02T15:37:17.000Z",
"excursion_at": "2024-02-02T16:07:17.000Z",
"returned_to_normal_at": null,
"acknowledged_at": "2024-02-02T15:52:17.000Z",
"relationships": {
"comments": {
"data": [
],
"meta": {
"count": 0
}
}
},
"severity": "excursion",
"acknowledger": {
"id": 48,
"account_id": 38,
"email": "stokes_susy@pacocha.test",
"full_name": "Susy Stokes",
"first_name": "Susy",
"last_name": "Stokes",
"current_login_at": "2024-02-02T15:37:17.000Z",
"last_login_at": "2024-02-02T14:37:17.000Z",
"last_request_at": "2024-02-02T16:32:17.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
"location": {
"id": 42,
"name": "Strosin, Simonis and Stiedemann",
"sublocation_ids": [
],
"resource": "Location"
},
"device": {
"name": "Attic fan 50",
"token": "791336753169654301",
"sku": "B00067Q8TY",
"serial": "24cf4e3f8547b379",
"battery": null,
"firmware": "0.53.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "11"
}
],
"meta": {
"count": 1
}
},
"channels": {
"meta": {
"count": 1
}
}
}
},
"channel": {
"id": 18,
"uuid": "41abd32c-dbb4-47b0-85ed-649e80e7fcef",
"name": "Temperature CH:18",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-02-02T16:37:17.000Z",
"last_datapoint_at": "2024-02-02T16:21:17.000Z",
"resource": "Channel",
"sensor": 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 unique identifier for this Alert record. |
|
description |
The condition which resulted in the alert. |
|
severity |
The severity of alert. Either |
|
type |
The type of alert. Either |
|
escalation_started_at |
An ISO-8601 timestamp representing the time that DicksonOne began monitoring the alert. |
|
entered_at |
An ISO-8601 timestamp representing the time that DicksonOne initially sent notifications for the alert. |
|
excursion_at |
An ISO-8601 timestamp representing the time that the alert was promoted to an excursion. |
|
returned_to_normal_at |
An ISO-8601 timestamp representing the time that the alert was resolved. |
|
acknowledged_at |
An ISO-8601 timestamp representing the time that the alert was acknowledged. |
|
acknowledger |
The data for the user that acknowledged the alert. |
|
location |
The data for the location in which this alert took place. |
|
device |
The data for the data logger related to this alert. |
|
channel |
The data for the channel related to this alert. This will be null for logger-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][]=964322285772219108&search[severity]=warning&search[started_after]=2024-02-02T13%3A37%3A19Z 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 data loggers to which you want to restrict your search. |
| search[channel_ids] |
A list of IDs for the channels to which you want to restrict your search. |
| search[location_ids] |
A list of IDs for the locations to which you want to restrict your search. |
| search[severity] |
The severity of alerts to which you want to restrict your search. Acceptable values are |
| search[type] |
The type of alerts to which you want to restrict your search. Acceptable values are |
| search[started_after] |
An ISO-8601 timestamp. Results will be filtered to alerts triggered after this time. |
| search[started_before] |
An ISO-8601 timestamp. Results will be filtered to alerts triggered prior to this time. |
| search[ended_after] |
An ISO-8601 timestamp. Results will be filtered to alerts resolved after this time. |
| search[ended_before] |
An ISO-8601 timestamp. Results will be filtered to alerts resolved prior to this time. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"active": 1,
"cleared": 1,
"excursion": 0,
"warning": 2
},
"meta": {
}
}Fields
| Name | Description |
|---|---|
|
active |
An integer count of active alert records. |
|
cleared |
An integer count of resolved alert records. |
|
excursion |
An integer count of alerts with an excursion severity. |
|
warning |
An integer count of alerts with a warning severity. |
Locations
View the location hierarchy for your account. Locations are structured with one root location attached directly to your account, and potentially multiple sublocations for every location.
[
{"id": 1, "name": "Account (Root)", "sublocation_ids": [2]},
{"id": 2, "name": "Warehouse", "sublocation_ids": []}
]
The following list might represent a simple location hierarchy for an organization monitoring a single warehouse:
- Account (Root) [1]
- Warehouse [2]
In order to reconstruct the full location hierarchy from the response, you
can start with the root location element (the first element in the list),
and follow the sublocation_ids for that location, nesting the locations
with the specified IDs beneath the root. You can then repeat this process
for each sublocation, stopping when you reach a location with no
sublocation_ids. Let’s look at an example for a slightly more complicated
organization.
[
{"id": 1, "name": "Account (Root)", "sublocation_ids": [2]},
{"id": 2, "name": "Region", "sublocation_ids": [3, 4]},
{"id": 3, "name": "Office #1", "sublocation_ids": []},
{"id": 4, "name": "Office #2", "sublocation_ids": []}
]
The following list might represent an organization with a deeper location hierarchy, due to a high density of sensors, or sensors used for multiple purposes or applications throughout the organization:
- Account (Root) [1]
- Region [2]
- Office #1 [3]
- Office #2 [4]
- Region [2]
As above, you can follow the sublocation_ids starting with the root
location to reconstruct the proper hierarchy for your organization.
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/45 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": 45,
"name": "Kertzmann LLC",
"sublocation_ids": [
],
"resource": "Location",
"devices": [
{
"name": "Clothes dryer 53",
"token": "353156320171759394",
"sku": "B0000DFH0E",
"serial": "bdf69ecd08a4a26b",
"battery": null,
"firmware": "0.56.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
},
{
"name": "Cold-pressed juicer 54",
"token": "481942404288934121",
"sku": "B000GLXHGC",
"serial": "ad8dbd029c164975",
"battery": null,
"firmware": "0.57.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": 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
}
}
},
"permission": "edit"
}
}Fields
| Name | Description |
|---|---|
|
id |
The location’s unique identifier. |
|
name |
The location’s name. |
|
permission |
The current user’s level of access to this location. |
|
devices |
A list of data loggers attached to this location. |
|
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][]=47&search[ids][]=48&search[ids][]=49 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. |
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": 51,
"name": "Kuphal Inc",
"sublocation_ids": [
52,
53
],
"resource": "Location",
"relationships": {
},
"permission": "edit"
},
{
"id": 52,
"name": "Porch 4",
"sublocation_ids": [
],
"resource": "Location",
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
},
"devices": {
"meta": {
"count": 2
}
}
},
"permission": "edit"
},
{
"id": 53,
"name": "Kitchen 5",
"sublocation_ids": [
],
"resource": "Location",
"relationships": {
},
"permission": "edit"
}
],
"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. |
|
permission |
The current user’s level of access to this location. |
|
sublocation_ids |
A list of IDs for the locations nested beneath this one. |
Registrations
Review, claim, and register the data loggers that have reported through RF Gateways registered to your account.
Listing registration candidates
Retrieve a list of all RF data loggers that have been associated with your account. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/registrations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
GET /api/rest/registrations
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"token": "964952893207924073",
"name": null,
"sku": "B000B5MVJM",
"serial": "10384c5c8403adb2",
"registration_code": "136973",
"registered_at": null,
"service_name": "dicksonone.com"
},
{
"token": "966721117350068611",
"name": null,
"sku": "B000GPHRW8",
"serial": "c6800d5ec9da6ed2",
"registration_code": "163634",
"registered_at": null,
"service_name": "dicksonone.com"
}
],
"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 logger’s unique identifier. |
|
name |
The logger’s name. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
registration_code |
The logger’s displayed registration code. |
Registering a service logger
Register the targeted logger to your account for the specified service. This will register the logger with the requested service, and perform a modified subscription check to ensure that loggers are counted toward the limits for the correct service.
Request
POST /api/rest/devices/449524506569887519/registrations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"device": {
"name": "My Newly-Registered Logger",
"service_name": "test.dicksonone.com",
"location_id": 57
}
}Endpoint
POST /api/rest/devices/:token/registrations
Parameters
| Name | Description |
|---|---|
| device[name] |
The name to give the data logger upon registration. Defaults to the logger’s serial number, if not provided. |
| device[service_name] |
The name of the service that is registering the logger. |
| device[location_id] |
The ID of the location to which the logger should be assigned. Defaults to the account’s root location. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"token": "449524506569887519",
"name": "My Newly-Registered Logger",
"sku": "B000H4CQYM",
"serial": "dd49d74c13fd3f78",
"registration_code": "649628",
"registered_at": "2024-02-02T16:37:22.000Z",
"service_name": "test.dicksonone.com"
}
}Fields
| Name | Description |
|---|---|
|
token |
The logger’s unique identifier. |
|
name |
The logger’s name. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
registered_at |
The timestamp of the logger’s successful registration. |
|
service_name |
The name of the service that the logger is registered with. Defaults to |
Registering an available logger
Register the targeted logger to your account. This will increment the number of loggers associated with your current DicksonOne subscription and allow the logger to start collecting and displaying readings data.
Request
POST /api/rest/devices/474894868417856015/registrations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"device": {
"name": "My Newly-Registered Logger"
}
}Endpoint
POST /api/rest/devices/:token/registrations
Parameters
| Name | Description |
|---|---|
| device[name] |
The name to give the data logger upon registration. Defaults to the logger’s serial number, if not provided. |
| device[service_name] |
The name of the service that is registering the logger. |
| device[location_id] |
The ID of the location to which the logger should be assigned. Defaults to the account’s root location. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"token": "474894868417856015",
"name": "My Newly-Registered Logger",
"sku": "B00067OVMK",
"serial": "1e3eda9a8e092942",
"registration_code": "939493",
"registered_at": "2024-02-02T16:37:23.000Z",
"service_name": "dicksonone.com"
}
}Fields
| Name | Description |
|---|---|
|
token |
The logger’s unique identifier. |
|
name |
The logger’s name. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
registered_at |
The timestamp of the logger’s successful registration. |
|
service_name |
The name of the service that the logger is registered with. Defaults to |
Encountering a registration issue
Registration of available RF data loggers is contingent on the details of the active subscription for your account. In the event that a logger cannot be successfully registered to your account for any reason, the response will include information about the error encountered.
Request
POST /api/rest/devices/831774768787183062/registrations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
POST /api/rest/devices/:token/registrations
Parameters
| Name | Description |
|---|---|
| device[name] |
The name to give the data logger upon registration. Defaults to the logger’s serial number, if not provided. |
| device[service_name] |
The name of the service that is registering the logger. |
| device[location_id] |
The ID of the location to which the logger should be assigned. Defaults to the account’s root location. |
Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
{
"errors": [
{
"status": "422",
"title": "Validation Error",
"detail": "You cannot add any more data loggers because your subscription has reached its maximum limit.",
"source": {
"pointer": "/data/attributes/base"
},
"meta": {
"attribute": "base",
"code": "over_subscription_max",
"message": "You cannot add any more data loggers because your subscription has reached its maximum limit."
}
}
]
}Fields
| Name | Description |
|---|---|
|
errors |
A list of the errors that prevented the logger from being registered. |
Claiming additional loggers for registration
In the event that a data logger in your possession doesn’t show up in the list of registration candidates, it may be necessary to explicitly claim the logger using the registration code displayed on its screen.
This will assign the logger to your account, ensuring that it’s included in the list of registerable loggers.
Request
POST /api/rest/devices/102305/claims HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
POST /api/rest/devices/:code/claims
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {
"token": "147625854130828286",
"name": null,
"sku": "B0009PC1XA",
"serial": "9acd0531d05a979c",
"registration_code": "102305",
"registered_at": null,
"service_name": "dicksonone.com"
}
}Fields
| Name | Description |
|---|---|
|
token |
The logger’s unique identifier. |
|
name |
The logger’s name. |
|
sku |
The logger’s model/SKU. |
|
serial |
The logger’s serial number. |
|
registration_code |
The logger’s displayed registration code. |
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 data loggers, channels, and/or locations. 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, data logger, or location. |
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": 32,
"uuid": "075c8d72-fa70-4d60-b462-6ccba2793712",
"name": "Office Door",
"type": "Boolean",
"unit": "boolean",
"first_datapoint_at": "2024-01-19T16:37:26.000Z",
"last_datapoint_at": "2024-02-02T16:23:26.000Z",
"resource": "Channel",
"sensor": null,
"summary_url": "http://dps.lvh.me/datapoints/075c8d72-fa70-4d60-b462-6ccba2793712/1705682246/1706891006/summary",
"readings_urls": [
"http://dps.lvh.me/datapoints/075c8d72-fa70-4d60-b462-6ccba2793712/1705682246/1706891006"
],
"device": {
"name": "Fridge",
"token": "218794125247299386",
"sku": "B0009XDRTE",
"serial": "0a599b99927feebd",
"battery": null,
"firmware": "0.76.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 2
}
}
}
},
"location": {
"id": 66,
"name": "Ruby Office",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
},
{
"name": "Office",
"token": "177824573206484737",
"sku": "B0000DGFW7",
"serial": "c6cb7f70176b874d",
"battery": null,
"firmware": "0.77.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
},
"channels": [
],
"location": {
"id": 66,
"name": "Ruby Office",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"id": 66,
"name": "Ruby Office",
"sublocation_ids": [
],
"resource": "Location",
"devices": [
{
"name": "Fridge",
"token": "218794125247299386",
"sku": "B0009XDRTE",
"serial": "0a599b99927feebd",
"battery": null,
"firmware": "0.76.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 2
}
}
}
},
{
"name": "Office",
"token": "177824573206484737",
"sku": "B0000DGFW7",
"serial": "c6cb7f70176b874d",
"battery": null,
"firmware": "0.77.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
}
},
{
"name": "Garage",
"token": "787763388559976453",
"sku": "B0000DECN1",
"serial": "46d0b6445b1870f2",
"battery": null,
"firmware": "0.78.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": 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": 67,
"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 |
Channels
View the channels reporting for the data loggers 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 logger. 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 data logger. |
| unit | The unit in which the reading is stored. |
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 Data Logger Overview graph.
Request
POST /api/rest/channels/133/annotations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"annotation": {
"content": "Minus commodi sed. Sed nulla rerum. Sed et laborum.",
"at": "2024-01-26T16:37:33Z"
}
}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": "Minus commodi sed. Sed nulla rerum. Sed et laborum.",
"at": "2024-01-26T16:37:33.000Z",
"channel": {
"id": 133,
"uuid": "509776f4-4adb-4e82-9f98-e670facea5fc",
"name": "Temperature CH:133",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"sensor": null
},
"user": {
"id": 64,
"account_id": 54,
"email": "schmeler_rachal@goodwin.example",
"full_name": "Rachal Schmeler",
"first_name": "Rachal",
"last_name": "Schmeler",
"current_login_at": "2024-02-02T15:37:33.000Z",
"last_login_at": "2024-02-01T16:37:33.000Z",
"last_request_at": "2024-02-02T16:37:33.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
}
}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. |
Removing a channel annotation
Delete the specified annotation.
Request
DELETE /api/rest/channels/134/annotations/6 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
Endpoint
DELETE /api/rest/channels/:channel_id/annotations/:id
Listing account channels
Retrieve a list of all channels reporting for data loggers 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": 136,
"uuid": "7d63e121-6afa-4079-b3ff-00b25e08264c",
"name": "Temperature CH:136",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-01-12T16:37:35.000Z",
"last_datapoint_at": "2024-02-02T16:36:35.000Z",
"resource": "Channel",
"sensor": null,
"device": {
"name": "Ceiling fan 89",
"token": "829340296985977183",
"sku": "B000AR9FZE",
"serial": "534e21b8750f8d64",
"battery": null,
"firmware": "0.101.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"warnings": {
"data": [
{
"type": "alert",
"id": "24"
}
],
"meta": {
"count": 1
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "23"
}
],
"meta": {
"count": 1
}
},
"channels": {
"meta": {
"count": 1
}
}
}
},
"location": {
"id": 103,
"name": "Daniel, Rolfson and Ullrich",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
{
"type": "alert",
"id": "24"
}
],
"meta": {
"count": 1
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "23"
}
],
"meta": {
"count": 1
}
}
}
},
{
"id": 137,
"uuid": "e39383ba-342f-43b9-8494-bfa3cc2c7f11",
"name": "Relative Humidity CH:137",
"type": "RelativeHumidity",
"unit": "rh",
"first_datapoint_at": "2024-02-02T16:37:35.000Z",
"last_datapoint_at": "2024-02-02T16:33:35.000Z",
"resource": "Channel",
"sensor": null,
"device": {
"name": "Washing machine 90",
"token": "480261447669241673",
"sku": "B0000AAGDL",
"serial": "70073b1eea826eac",
"battery": null,
"firmware": "0.102.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
},
"location": {
"id": 103,
"name": "Daniel, Rolfson and Ullrich",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
],
"meta": {
"count": 0
}
},
"excursions": {
"data": [
],
"meta": {
"count": 0
}
}
}
}
],
"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 data logger 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%3A138 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": 138,
"uuid": "8d3876d1-0a5c-4a2b-b2f4-21b2bab36a43",
"name": "Temperature CH:138",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-02-02T16:37:35.000Z",
"last_datapoint_at": "2024-02-02T16:33:35.000Z",
"resource": "Channel",
"sensor": null,
"device": {
"name": "Dishwasher 91",
"token": "768412876312340194",
"sku": "B000A70EAO",
"serial": "c74ed3f5e4e84d68",
"battery": null,
"firmware": "0.103.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"warnings": {
"data": [
{
"type": "alert",
"id": "27"
}
],
"meta": {
"count": 1
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "26"
}
],
"meta": {
"count": 1
}
},
"channels": {
"meta": {
"count": 1
}
}
}
},
"location": {
"id": 104,
"name": "Zboncak, Swift and Hudson",
"sublocation_ids": [
],
"resource": "Location"
},
"relationships": {
"warnings": {
"data": [
{
"type": "alert",
"id": "27"
}
],
"meta": {
"count": 1
}
},
"excursions": {
"data": [
{
"type": "alert",
"id": "26"
}
],
"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 data logger 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/140/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": 7,
"content": "Maiores eaque quia. Quos qui molestias.",
"at": "2024-01-02T16:37:36.000Z",
"channel": {
"id": 140,
"uuid": "f2fb8036-ed69-4d70-bf74-00d77f4cd2e2",
"name": "Temperature CH:140",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"sensor": null
},
"user": {
"id": 70,
"account_id": 60,
"email": "betty.farrell@cummings.test",
"full_name": "Betty Farrell",
"first_name": "Betty",
"last_name": "Farrell",
"current_login_at": "2024-02-02T15:37:36.000Z",
"last_login_at": "2024-02-01T16:37:36.000Z",
"last_request_at": "2024-02-02T16:32:36.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
},
{
"id": 8,
"content": "Est molestiae vel. Corporis qui ab.",
"at": "2024-01-19T16:37:36.000Z",
"channel": {
"id": 140,
"uuid": "f2fb8036-ed69-4d70-bf74-00d77f4cd2e2",
"name": "Temperature CH:140",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"sensor": null
},
"user": {
"id": 71,
"account_id": 61,
"email": "jasmine_kerluke@weimann-ritchie.test",
"full_name": "Jasmine Kerluke",
"first_name": "Jasmine",
"last_name": "Kerluke",
"current_login_at": "2024-02-02T15:37:36.000Z",
"last_login_at": "2024-02-01T16:37:36.000Z",
"last_request_at": "2024-02-02T16:32:36.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
}
],
"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/143/annotations?search[after]=2023-12-29T16%3A37%3A38Z&search[before]=2024-01-12T16%3A37%3A38Z 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": 9,
"content": "Error ut reiciendis. Eum voluptatem quia.",
"at": "2024-01-02T16:37:37.000Z",
"channel": {
"id": 143,
"uuid": "452b9449-7a83-436e-8395-fe18c5d6d890",
"name": "Temperature CH:143",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"sensor": null
},
"user": {
"id": 73,
"account_id": 63,
"email": "hegmann_tonya@mcglynn.example",
"full_name": "Tonya Hegmann",
"first_name": "Tonya",
"last_name": "Hegmann",
"current_login_at": "2024-02-02T15:37:37.000Z",
"last_login_at": "2024-02-01T16:37:37.000Z",
"last_request_at": "2024-02-02T16:32:37.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
}
],
"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. |
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 logger.
Request
GET /api/rest/channels/146?readings[after]=2024-01-28T16%3A37%3A38Z&readings[before]=2024-01-29T16%3A37%3A38Z 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": 146,
"uuid": "64fe70dd-ed62-470d-b6f3-ab9ce8b2c22c",
"name": "Differential Pressure CH:146",
"type": "DifferentialPressure",
"unit": "inches_h2o",
"first_datapoint_at": "2024-02-02T16:37:38.000Z",
"last_datapoint_at": "2024-02-02T16:29:38.000Z",
"resource": "Channel",
"sensor": null,
"summary_url": "http://dps.lvh.me/datapoints/64fe70dd-ed62-470d-b6f3-ab9ce8b2c22c/1706459858/1706546258/summary",
"readings_urls": [
"http://dps.lvh.me/datapoints/64fe70dd-ed62-470d-b6f3-ab9ce8b2c22c/1706459858/1706546258"
],
"device": {
"name": "Home server 95",
"token": "435938382342218749",
"sku": "B0007Z6BBA",
"serial": "020d9558eb2ab3d3",
"battery": null,
"firmware": "0.107.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
},
"location": {
"id": 111,
"name": "Purdy Inc",
"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 data logger that is associated with this channel. |
Listing channels by data logger
Retrieve a list of the channels reporting for a specific logger. This list is paginated. For more information about interacting with paginated data, see Pagination.
Request
GET /api/rest/devices/607640782512771364/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": 147,
"uuid": "f4e1b02d-0247-45b3-b0ee-608009d0b729",
"name": "Temperature CH:147",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": "2024-01-26T16:37:39.000Z",
"last_datapoint_at": "2024-02-02T16:19:39.000Z",
"resource": "Channel",
"sensor": {
"id": 1,
"serial": "360-12-2590",
"model": "Stronghold",
"factory_calibration_date": "2023-07-10T00:00:00.000Z",
"user_calibration_date": "2023-08-02T00:00:00.000Z",
"created_at": "2024-02-02T16:37:39.000Z",
"updated_at": "2024-02-02T16:37:39.000Z"
},
"device": {
"name": "Blender 96",
"token": "607640782512771364",
"sku": "B000GLXHGC",
"serial": "0629e30b5a374ef9",
"battery": null,
"firmware": "0.108.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 1
}
}
}
},
"location": {
"id": 112,
"name": "Gorczany, Wilkinson and Kessler",
"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. |
|
device |
The data logger that is associated with this channel. |
|
sensor |
The sensor that is associated with this channel. |
Updating a channel annotation
Update the specified annotation with new content or a modified timestamp.
Request
PATCH /api/rest/channels/149/annotations/11 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json
{
"annotation": {
"content": "Odio minus explicabo. Illo ut aliquam. Quae earum ipsum."
}
}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": 11,
"content": "Odio minus explicabo. Illo ut aliquam. Quae earum ipsum.",
"at": "2024-02-02T16:37:40.000Z",
"channel": {
"id": 149,
"uuid": "5df552f3-05da-47a8-9de8-7d61743c793a",
"name": "Temperature CH:149",
"type": "Temperature",
"unit": "fahrenheit",
"first_datapoint_at": null,
"last_datapoint_at": null,
"resource": "Channel",
"sensor": null
},
"user": {
"id": 78,
"account_id": 68,
"email": "bradtke.conrad@braun-bergstrom.example",
"full_name": "Conrad Bradtke",
"first_name": "Conrad",
"last_name": "Bradtke",
"current_login_at": "2024-02-02T15:37:40.000Z",
"last_login_at": "2024-02-01T16:37:40.000Z",
"last_request_at": "2024-02-02T16:32:40.000Z",
"time_zone": "America/Chicago",
"role": null,
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
}
}
}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. |
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 data logger or update of logger settings. |
| EscalationPolicy | Activity tied to the creation or update of notification policies on the account. |
| Export | Activity tied to generation of account, data logger, or equipment 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": 10,
"message": "Data Logger setting(s) updated:\n - Temperature Display Unit changed to \"°C\" from \"°F\"",
"created_at": "2024-02-02T16:07:40.000Z",
"type": "Device",
"user": {
"id": 79,
"account_id": 69,
"email": "block_donn@crona.test",
"full_name": "Donn Block",
"first_name": "Donn",
"last_name": "Block",
"current_login_at": "2024-02-02T15:37:40.000Z",
"last_login_at": "2024-02-01T16:37:40.000Z",
"last_request_at": "2024-02-02T16:37:40.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
"device": {
"name": "Domestic robot 98",
"token": "751813296801580662",
"sku": "B000A2O26G",
"serial": "caf2d4dab2224e55",
"battery": null,
"firmware": "0.110.0",
"last_datapoint_at": null,
"last_reported_at": null,
"archived_at": null,
"is_replaced": false,
"resource": "Device",
"relationships": {
"channels": {
"meta": {
"count": 0
}
}
}
},
"location": {
"id": 115,
"name": "Goyette-Johnson",
"sublocation_ids": [
],
"resource": "Location"
}
},
{
"id": 9,
"message": "Logged In",
"created_at": "2024-02-02T15:47:40.000Z",
"type": "User",
"user": {
"id": 79,
"account_id": 69,
"email": "block_donn@crona.test",
"full_name": "Donn Block",
"first_name": "Donn",
"last_name": "Block",
"current_login_at": "2024-02-02T15:37:40.000Z",
"last_login_at": "2024-02-01T16:37:40.000Z",
"last_request_at": "2024-02-02T16:37:40.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
"device": null,
"location": null
},
{
"id": 8,
"message": "Failed Login Attempt",
"created_at": "2024-02-02T15:37:40.000Z",
"type": "User",
"user": {
"id": 79,
"account_id": 69,
"email": "block_donn@crona.test",
"full_name": "Donn Block",
"first_name": "Donn",
"last_name": "Block",
"current_login_at": "2024-02-02T15:37:40.000Z",
"last_login_at": "2024-02-01T16:37:40.000Z",
"last_request_at": "2024-02-02T16:37:40.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
"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 data logger 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][]=80&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 data loggers 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 data loggers 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": 12,
"message": "Logged In",
"created_at": "2024-02-02T15:47:41.000Z",
"type": "User",
"user": {
"id": 80,
"account_id": 70,
"email": "kunze.bettye@heller.example",
"full_name": "Bettye Kunze",
"first_name": "Bettye",
"last_name": "Kunze",
"current_login_at": "2024-02-02T15:37:41.000Z",
"last_login_at": "2024-02-01T16:37:41.000Z",
"last_request_at": "2024-02-02T16:37:41.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
"device": null,
"location": null
},
{
"id": 11,
"message": "Failed Login Attempt",
"created_at": "2024-02-02T15:37:41.000Z",
"type": "User",
"user": {
"id": 80,
"account_id": 70,
"email": "kunze.bettye@heller.example",
"full_name": "Bettye Kunze",
"first_name": "Bettye",
"last_name": "Kunze",
"current_login_at": "2024-02-02T15:37:41.000Z",
"last_login_at": "2024-02-01T16:37:41.000Z",
"last_request_at": "2024-02-02T16:37:41.000Z",
"time_zone": "America/Chicago",
"role": "manager",
"locale": "en",
"datetime_format": "MM/DD/YYYY h:mm:ss TT"
},
"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 data logger 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 data loggers 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 data loggers 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. |