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.

Base URL

Code examples below assume that requests are being directed to endpoints for the application at a base URL. All listed request endpoints should be directed to the following domain:

https://www.dicksonone.com

Authentication

GET https://www.dicksonone.com/api/rest/users HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN

The DicksonOne API uses API keys to authenticate requests. Account Managers and Owners can manage the API keys available for their account via “Manage > API Keys”. Use of this API requires that your account have an active subscription with an appropriate level of features. If you’re interested in accessing the REST API and don’t currently have access to API Key management, please contact support@dicksonone.com to discuss upgrading your subscription.

In order to access the API, you’ll need to pass the token associated with an active API Key as a Bearer token in the Authorization header for each request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Pagination

Due to the large number of records that can be returned with each request, DicksonOne’s REST API uses pagination to pass back records in manageable chunks.

Request

GET https://www.dicksonone.com/api/rest/locations?page[number]=2&page[size]=3 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

For API endpoints that return a collection of results, you can control which page of results you’re fetching, as well as the number of results included on each page, using the following pagination parameters.

Parameters

Response

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

{ 
  "data": [
    { "id": 4, "name": "Pharmaceutical Warehouse - West", "sublocation_ids": [5, 6] },
    { "id": 5, "name": "Vaccine Refrigerator A", "sublocation_ids": [] },
    { "id": 6, "name": "Vaccine Refrigerator B", "sublocation_ids": [] }
  ],
  "meta" : {
    "pagination": {
      "record_count": 7,
      "page_size": 3,
      "page_count": 3,
      "current_page": 2,
      "prev_page": 1,
      "next_page": 3
    }
  }
}

Each response for a paginated endpoint will include a set of metadata for the paginated results, in addition to the list of record data.

Fields

Errors

DicksonOne uses conventional HTTP response codes to indicate the success or failure of an API request.

Success Codes

• Codes in the 2xx range indicate a successful response.

Error Codes

• Codes in the 3xx range indicate that the request needs to be redirected.
• Codes in the 4xx range indicate that the content or structure of the request is invalid (e.g., a missing or blank parameter).
• Codes in the 5xx range indicate an error on DicksonOne’s servers.

Support

Dickson does not provide support for custom integrations. If you have general questions regarding access to or the functionality of the API, please email support@dicksonone.com. This code is provided “as is”, without warranty of any kind expressed or implied.

Alerts

View the alerts that have been triggered by devices on your account. Each Alert record represents a historical event that was caused by a Device tripping the warning or excursion condition for a configured Alarm.

Listing all alerts

Retrieve a list of all historical alerts for your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/alerts HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/alerts

Response

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

{
  "data": [
    {
      "id": 1,
      "description": "Temperature CH:1 is above 29.0°F",
      "type": "excursion",
      "escalation_started_at": "2019-09-09T02:50:44.000Z",
      "entered_at": "2019-09-09T03:20:44.000Z",
      "excursion_at": "2019-09-09T03:50:44.000Z",
      "returned_to_normal_at": null,
      "acknowledged_at": "2019-09-09T03:35:44.000Z",
      "acknowledger": {
        "id": 2,
        "email": "solomon.boehm@hagenes.name",
        "full_name": "Solomon Boehm",
        "first_name": "Solomon",
        "last_name": "Boehm",
        "current_login_at": "2019-09-09T03:20:44.000Z",
        "last_login_at": "2019-09-09T02:20:44.000Z",
        "last_request_at": "2019-09-09T04:20:44.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      },
      "location": {
        "id": 1,
        "name": "Hagenes-Friesen",
        "sublocation_ids": [

        ]
      },
      "device": {
        "name": "Central vacuum cleaner 1",
        "token": "985753884267345458",
        "sku": "B000A2LWKU",
        "serial": "263a2ce4ada096f4"
      },
      "channel": {
        "id": 1,
        "name": "Temperature CH:1",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2019-08-26T04:20:43.000Z",
        "last_datapoint_at": "2019-09-09T04:06:43.000Z"
      }
    },
    {
      "id": 2,
      "description": "Temperature CH:1 is above 29.0°F",
      "type": "warning",
      "escalation_started_at": "2019-09-09T02:20:44.000Z",
      "entered_at": "2019-09-09T02:50:44.000Z",
      "excursion_at": null,
      "returned_to_normal_at": "2019-09-09T03:20:44.000Z",
      "acknowledged_at": null,
      "acknowledger": null,
      "location": {
        "id": 1,
        "name": "Hagenes-Friesen",
        "sublocation_ids": [

        ]
      },
      "device": {
        "name": "Central vacuum cleaner 1",
        "token": "985753884267345458",
        "sku": "B000A2LWKU",
        "serial": "263a2ce4ada096f4"
      },
      "channel": {
        "id": 1,
        "name": "Temperature CH:1",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2019-08-26T04:20:43.000Z",
        "last_datapoint_at": "2019-09-09T04:06:43.000Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Listing filtered alerts

Retrieve a list of historical alerts for your account matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/alerts?search[tokens][]=337189713003826377&search[type]=excursion&search[started_after]=2019-09-09T01%3A20%3A45Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/alerts

Parameters

Response

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

{
  "data": [
    {
      "id": 3,
      "description": "Temperature CH:2 is above 17.0°F",
      "type": "excursion",
      "escalation_started_at": "2019-09-09T02:50:45.000Z",
      "entered_at": "2019-09-09T03:20:45.000Z",
      "excursion_at": "2019-09-09T03:50:45.000Z",
      "returned_to_normal_at": null,
      "acknowledged_at": "2019-09-09T03:35:45.000Z",
      "acknowledger": {
        "id": 4,
        "email": "stoltenberg_miguel@nolanwolf.co",
        "full_name": "Miguel Stoltenberg",
        "first_name": "Miguel",
        "last_name": "Stoltenberg",
        "current_login_at": "2019-09-09T03:20:45.000Z",
        "last_login_at": "2019-09-09T02:20:45.000Z",
        "last_request_at": "2019-09-09T04:20:45.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      },
      "location": {
        "id": 2,
        "name": "Tremblay and Sons",
        "sublocation_ids": [

        ]
      },
      "device": {
        "name": "Bachelor griller 2",
        "token": "337189713003826377",
        "sku": "B000KBAL6W",
        "serial": "3070019d50695ee6"
      },
      "channel": {
        "id": 2,
        "name": "Temperature CH:2",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2019-08-19T04:20:45.000Z",
        "last_datapoint_at": "2019-09-09T03:52:45.000Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 1,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Acknowledging an alert

Mark an alert as acknowledged. The acknowledger for the alert will be set to the User associated with the API token, and the acknowledged_at timestamp will be set to the time that the request was received by the server. Attempting to acknowledge an alert that has already been acknowledged will result in a 409 Conflict response.

Request

POST /api/rest/alerts/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:3 is above 78.0°F",
    "type": "excursion",
    "escalation_started_at": "2019-09-09T02:50:45.000Z",
    "entered_at": "2019-09-09T03:20:45.000Z",
    "excursion_at": "2019-09-09T03:50:45.000Z",
    "returned_to_normal_at": null,
    "acknowledged_at": "2019-09-09T04:20:45.000Z",
    "acknowledger": {
      "id": 5,
      "email": "tamra_lowe@dickicollins.io",
      "full_name": "Tamra Lowe",
      "first_name": "Tamra",
      "last_name": "Lowe",
      "current_login_at": "2019-09-09T03:20:45.000Z",
      "last_login_at": "2019-09-08T04:20:45.000Z",
      "last_request_at": "2019-09-09T04:20:45.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": "manager"
    },
    "location": {
      "id": 3,
      "name": "Swift and Sons",
      "sublocation_ids": [

      ]
    },
    "device": {
      "name": "Blender 3",
      "token": "593500512470219004",
      "sku": "B0002X4OIY",
      "serial": "ac9d6b89376f8b58"
    },
    "channel": {
      "id": 3,
      "name": "Temperature CH:3",
      "type": "Temperature",
      "unit": "fahrenheit",
      "first_datapoint_at": "2019-08-12T04:20:45.000Z",
      "last_datapoint_at": "2019-09-09T04:05:45.000Z"
    }
  }
}

Fields

Listing comments for an alert

Retrieve a list of comments that have been submitted for a particular alert. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/alerts/6/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": 2,
      "text": "Neque ut occaecati. Sapiente ex dolor.",
      "created_at": "2019-09-09T04:20:46.000Z",
      "user": {
        "id": 7,
        "email": "hoeger_laverne@dickinsonfunk.org",
        "full_name": "Laverne Hoeger",
        "first_name": "Laverne",
        "last_name": "Hoeger",
        "current_login_at": "2019-09-09T03:20:46.000Z",
        "last_login_at": "2019-09-08T04:20:46.000Z",
        "last_request_at": "2019-09-09T04:20:46.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    },
    {
      "id": 3,
      "text": "Quia ipsum dolorem. Labore nihil praesentium.",
      "created_at": "2019-09-09T04:20:46.000Z",
      "user": {
        "id": 7,
        "email": "hoeger_laverne@dickinsonfunk.org",
        "full_name": "Laverne Hoeger",
        "first_name": "Laverne",
        "last_name": "Hoeger",
        "current_login_at": "2019-09-09T03:20:46.000Z",
        "last_login_at": "2019-09-08T04:20:46.000Z",
        "last_request_at": "2019-09-09T04:20:46.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    },
    {
      "id": 4,
      "text": "Quia aut suscipit. Ducimus doloremque id.",
      "created_at": "2019-09-09T04:20:46.000Z",
      "user": {
        "id": 7,
        "email": "hoeger_laverne@dickinsonfunk.org",
        "full_name": "Laverne Hoeger",
        "first_name": "Laverne",
        "last_name": "Hoeger",
        "current_login_at": "2019-09-09T03:20:46.000Z",
        "last_login_at": "2019-09-08T04:20:46.000Z",
        "last_request_at": "2019-09-09T04:20:46.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 3,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Adding a comment to an alert

Add a comment to a specified Alert. If the Alert was not previously acknowledged, this action will also acknowledge the alert and mark the commenter as the acknowledger.

Request

POST /api/rest/alerts/7/comments HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "comment": {
    "text": "Eius a accusantium. Deserunt laborum maxime. Sit quis qui."
  }
}

Endpoint

POST /api/rest/alerts/:alert_id/comments

Parameters

Response

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

{
  "data": {
    "id": 5,
    "text": "Eius a accusantium. Deserunt laborum maxime. Sit quis qui.",
    "created_at": "2019-09-09T04:20:46.000Z",
    "user": {
      "id": 8,
      "email": "loren.ebert@johnsonmcclure.name",
      "full_name": "Loren Ebert",
      "first_name": "Loren",
      "last_name": "Ebert",
      "current_login_at": "2019-09-09T03:20:46.000Z",
      "last_login_at": "2019-09-08T04:20:46.000Z",
      "last_request_at": "2019-09-09T04:20:46.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": "manager"
    }
  }
}

Fields

Channels

View the channels reporting for the devices on your account. Each Channel record represents a single stream of data coming in from a sensor plugged in to one of your environmental loggers. One sensor can potentially report multiple Channels’ worth of data to DicksonOne.

Fetching channel data

Readings data for DicksonOne is served out of a separate Datapoint Service. When you fetch information for a channel, the response includes the URLs necessary to fetch the data for that channel.

All readings data is normalized to a single unit for storage purposes (e.g., all temperature readings are stored in Fahrenheit). When you view your data in exports, reports, or the DicksonOne interface, we perform a conversion from the stored unit to the display unit configured for your device. If you’re building a custom integration and want to see the readings values in a different unit, you’ll need to convert the raw readings data yourself.

Summary data

GET https://dps.dicksonone.com/datapoints/036390d0-f790-4cf6-b903-cc0ee63f49b7/1566364361/1566450761/summary HTTP/1.1

The summary_url for a channel gives a full summary of the data for the channel over its reporting lifetime.

Summary response

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

{
  "summary":{
    "count": 289,
    "min": 13.9,
    "max": 15.1,
    "avg": 14.5764705882353,
    "mkt": 14.5800856751846,
    "min_ts": 1566385361,
    "max_ts": 1566447761,
    "unit":"f"
  }
}

Fields

Readings data

GET https://dps.dicksonone.com/datapoints/036390d0-f790-4cf6-b903-cc0ee63f49b7/1566364361/1566365561 HTTP/1.1

The readings_urls for a channel lists a series of URLs for segments of data. Fetching the data at these URLs will yield all of the readings that have been recorded for the channel over its reporting lifetime.

Readings response

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

{
  "records":[
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364361, "value": 14.5, "unit": "f"},
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364661, "value": 14.6, "unit": "f"},
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566364961, "value": 14.8, "unit": "f"},
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566365261, "value": 14.9, "unit": "f"},
    {"channel": "036390d0-f790-4cf6-b903-cc0ee63f49b7", "ts": 1566365561, "value": 14.5, "unit": "f"}
  ]
}

Fields

Listing account channels

Retrieve a list of all channels reporting for devices belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/channels HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/channels

Response

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

{
  "data": [
    {
      "id": 4,
      "name": "Temperature CH:4",
      "type": "Temperature",
      "unit": "fahrenheit",
      "first_datapoint_at": "2019-09-02T04:20:47.000Z",
      "last_datapoint_at": "2019-09-09T03:58:47.000Z"
    },
    {
      "id": 5,
      "name": "Relative Humidity CH:5",
      "type": "RelativeHumidity",
      "unit": "rh",
      "first_datapoint_at": "2019-09-02T04:20:47.000Z",
      "last_datapoint_at": "2019-09-09T04:09:47.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Listing channels by device

Retrieve a list of the channels reporting for a specific device. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/devices/576823824696502660/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": 6,
      "name": "Temperature CH:6",
      "type": "Temperature",
      "unit": "fahrenheit",
      "first_datapoint_at": "2019-08-26T04:20:47.000Z",
      "last_datapoint_at": "2019-09-09T04:15:47.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 1,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Fetching a specific channel

By requesting details for a single channel, you can see more information, including URLs from which you can fetch readings and summary data for the device.

Request

GET /api/rest/channels/7?readings[after]=2019-09-05T18%3A44%3A22Z&readings[before]=2019-09-06T18%3A44%3A22Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/channels/:id

Parameters

Response

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

{
  "data": {
    "id": 7,
    "name": "Differential Pressure CH:7",
    "type": "DifferentialPressure",
    "unit": "inches_h2o",
    "first_datapoint_at": "2019-08-20T18:44:22.000Z",
    "last_datapoint_at": "2019-09-10T18:20:22.000Z",
    "summary_url": "https://dps.dicksonone.com/datapoints/af30ea7c-caaf-485b-9417-4967011b2e0b/1567709062/1567795462/summary",
    "readings_urls": [
      "https://dps.dicksonone.com/datapoints/af30ea7c-caaf-485b-9417-4967011b2e0b/1567709062/1567795462"
    ]
  }
}

Fields

Listing annotations for a channel

Retrieve a list of all annotations added to a specific channel. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/channels/8/annotations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/channels/:channel_id/annotations

Response

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

{
  "data": [
    {
      "id": 1,
      "content": "Atque soluta illo. Atque in exercitationem.",
      "at": "2019-08-09T04:20:48.000Z",
      "user": {
        "id": 13,
        "email": "greenholt_victoria@keeblerkemmer.com",
        "full_name": "Victoria Greenholt",
        "first_name": "Victoria",
        "last_name": "Greenholt",
        "current_login_at": "2019-09-09T03:20:48.000Z",
        "last_login_at": "2019-09-08T04:20:48.000Z",
        "last_request_at": "2019-09-09T04:20:48.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    },
    {
      "id": 2,
      "content": "Sint sed harum. Soluta suscipit eum.",
      "at": "2019-08-26T04:20:48.000Z",
      "user": {
        "id": 14,
        "email": "dino.krajcik@nienow.co",
        "full_name": "Dino Krajcik",
        "first_name": "Dino",
        "last_name": "Krajcik",
        "current_login_at": "2019-09-09T03:20:48.000Z",
        "last_login_at": "2019-09-08T04:20:48.000Z",
        "last_request_at": "2019-09-09T04:20:48.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Listing filtered annotations

Retrieve a list of annotations for the channel matching the specified search criteria. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/channels/11/annotations?search[after]=2019-08-06T18%3A44%3A24Z&search[before]=2019-08-20T18%3A44%3A24Z HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/channels/:channel_id/annotations

Parameters

Response

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

{
  "data": [
    {
      "id": 3,
      "content": "Culpa vitae ducimus. Est earum error.",
      "at": "2019-08-10T18:44:24.000Z",
      "user": {
        "id": 16,
        "email": "gerry_funk@manteebert.org",
        "full_name": "Gerry Funk",
        "first_name": "Gerry",
        "last_name": "Funk",
        "current_login_at": "2019-09-10T17:44:24.000Z",
        "last_login_at": "2019-09-09T18:44:24.000Z",
        "last_request_at": "2019-09-10T18:39:24.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": null
      }
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 1,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Adding a channel annotation

Add an annotation to the specified channel, at the specified time. Any added annotations will show up when the relevant time period is rendered on a Device Overview graph.

Request

POST /api/rest/channels/10/annotations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "annotation": {
    "content": "Temporibus accusamus modi. Ut delectus eveniet. Aliquid sit ut.",
    "at": "2019-09-02T04:20:49.000Z"
  }
}

Endpoint

POST /api/rest/channels/:channel_id/annotations

Parameters

Response

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

{
  "data": {
    "id": 5,
    "content": "Temporibus accusamus modi. Ut delectus eveniet. Aliquid sit ut.",
    "at": "2019-09-02T04:20:49.000Z",
    "user": {
      "id": 18,
      "email": "schulist.guadalupe@hammes.biz",
      "full_name": "Guadalupe Schulist",
      "first_name": "Guadalupe",
      "last_name": "Schulist",
      "current_login_at": "2019-09-09T03:20:49.000Z",
      "last_login_at": "2019-09-08T04:20:49.000Z",
      "last_request_at": "2019-09-09T04:20:49.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": "manager"
    }
  }
}

Fields

Updating a channel annotation

Update the specified annotation with new content or a modified timestamp.

Request

PATCH /api/rest/channels/11/annotations/6 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "annotation": {
    "content": "Laborum delectus iste. Voluptatem asperiores omnis. Ipsa aperiam unde."
  }
}

Endpoint

PATCH /api/rest/channels/:channel_id/annotations/:id

Parameters

Response

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

{
  "data": {
    "id": 6,
    "content": "Laborum delectus iste. Voluptatem asperiores omnis. Ipsa aperiam unde.",
    "at": "2019-09-09T04:20:50.000Z",
    "user": {
      "id": 20,
      "email": "clark.skiles@rennerhirthe.com",
      "full_name": "Clark Skiles",
      "first_name": "Clark",
      "last_name": "Skiles",
      "current_login_at": "2019-09-09T03:20:50.000Z",
      "last_login_at": "2019-09-08T04:20:50.000Z",
      "last_request_at": "2019-09-09T04:20:50.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": null
    }
  }
}

Fields

Removing a channel annotation

Delete the specified annotation.

Request

DELETE /api/rest/channels/12/annotations/7 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

DELETE /api/rest/channels/:channel_id/annotations/:id

Devices

View the devices configured for your account. Each Device record represents the current status of a particular environmental logger. Instead of integer IDs, Devices are thus accessed using a string token, which is maintained across device replacements.

Listing account devices

Retrieve a list of all devices belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/devices HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/devices

Response

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

{
  "data": [
    {
      "name": "Exhaust hood 17",
      "token": "844406528065713751",
      "sku": "B0007WHCXE",
      "serial": "7760be3e77d03cae"
    },
    {
      "name": "Flame supervision device 18",
      "token": "437686461088745045",
      "sku": "B0000DKWL7",
      "serial": "60544fe2a05b0f3e"
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Listing devices by location

Retrieve a list of the devices attached to a specific location. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/locations/24/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": "Space heater 19",
      "token": "543812595263534334",
      "sku": "B000AOVECO",
      "serial": "76a1757da76ca712"
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 1,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Fetching a specific device

By requesting details for a single device, you can see more information, including the channel metadata for that device.

Request

GET /api/rest/devices/580005346818424372 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/devices/:token

Response

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

{
  "data": {
    "name": "Evaporative cooler 20",
    "token": "580005346818424372",
    "sku": "B000CFIMWQ",
    "serial": "e1167bc177f267d7",
    "channels": [
      {
        "id": 13,
        "name": "Temperature CH:13",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2019-09-09T04:20:51.000Z",
        "last_datapoint_at": "2019-09-09T03:52:51.000Z"
      },
      {
        "id": 14,
        "name": "Temperature CH:14",
        "type": "Temperature",
        "unit": "fahrenheit",
        "first_datapoint_at": "2019-08-26T04:20:51.000Z",
        "last_datapoint_at": "2019-09-09T04:10:51.000Z"
      }
    ]
  }
}

Fields

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.

Listing all events

Retrieve a list of all events for your account, in reverse chronological order. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/events HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/events

Response

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

{
  "data": [
    {
      "id": 7,
      "message": "Device setting(s) updated:\n  - Temperature Display Unit changed to \"°C\" from \"°F\"",
      "created_at": "2019-09-09T03:50:51.000Z",
      "type": "Device",
      "user": {
        "id": 26,
        "email": "langosh_alonzo@fisher.io",
        "full_name": "Alonzo Langosh",
        "first_name": "Alonzo",
        "last_name": "Langosh",
        "current_login_at": "2019-09-09T03:20:51.000Z",
        "last_login_at": "2019-09-08T04:20:51.000Z",
        "last_request_at": "2019-09-09T04:20:51.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": {
        "name": "Forced-air 21",
        "token": "503886145912627036",
        "sku": "B000I6ONRM",
        "serial": "2ea2c9f387b47a8c"
      },
      "location": {
        "id": 26,
        "name": "Heidenreich, Schulist and Prohaska",
        "sublocation_ids": [

        ]
      }
    },
    {
      "id": 6,
      "message": "Logged In",
      "created_at": "2019-09-09T03:30:51.000Z",
      "type": "User",
      "user": {
        "id": 26,
        "email": "langosh_alonzo@fisher.io",
        "full_name": "Alonzo Langosh",
        "first_name": "Alonzo",
        "last_name": "Langosh",
        "current_login_at": "2019-09-09T03:20:51.000Z",
        "last_login_at": "2019-09-08T04:20:51.000Z",
        "last_request_at": "2019-09-09T04:20:51.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": null,
      "location": null
    },
    {
      "id": 5,
      "message": "Failed Login Attempt",
      "created_at": "2019-09-09T03:20:51.000Z",
      "type": "User",
      "user": {
        "id": 26,
        "email": "langosh_alonzo@fisher.io",
        "full_name": "Alonzo Langosh",
        "first_name": "Alonzo",
        "last_name": "Langosh",
        "current_login_at": "2019-09-09T03:20:51.000Z",
        "last_login_at": "2019-09-08T04:20:51.000Z",
        "last_request_at": "2019-09-09T04:20:51.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": null,
      "location": null
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 3,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

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][]=27&search[type]=User HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/events

Parameters

Response

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

{
  "data": [
    {
      "id": 9,
      "message": "Logged In",
      "created_at": "2019-09-09T03:30:52.000Z",
      "type": "User",
      "user": {
        "id": 27,
        "email": "myles.kozey@reinger.com",
        "full_name": "Myles Kozey",
        "first_name": "Myles",
        "last_name": "Kozey",
        "current_login_at": "2019-09-09T03:20:52.000Z",
        "last_login_at": "2019-09-08T04:20:52.000Z",
        "last_request_at": "2019-09-09T04:20:52.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": null,
      "location": null
    },
    {
      "id": 8,
      "message": "Failed Login Attempt",
      "created_at": "2019-09-09T03:20:52.000Z",
      "type": "User",
      "user": {
        "id": 27,
        "email": "myles.kozey@reinger.com",
        "full_name": "Myles Kozey",
        "first_name": "Myles",
        "last_name": "Kozey",
        "current_login_at": "2019-09-09T03:20:52.000Z",
        "last_login_at": "2019-09-08T04:20:52.000Z",
        "last_request_at": "2019-09-09T04:20:52.000Z",
        "time_zone": "Central Time (US & Canada)",
        "role": "manager"
      },
      "device": null,
      "location": null
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 2,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

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

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "errors": [
    "The requested type (Other) is not supported."
  ]
}

Fields

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]

As above, you can follow the sublocation_ids starting with the root location to reconstruct the proper hierarchy for your organization.

Listing account locations

Retrieve a list of locations belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/locations HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/locations

Response

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

{
  "data": [
    {
      "id": 29,
      "name": "Stracke Inc",
      "sublocation_ids": [
        30,
        31
      ]
    },
    {
      "id": 30,
      "name": "Reception Room 2",
      "sublocation_ids": [

      ]
    },
    {
      "id": 31,
      "name": "Drawing Room 3",
      "sublocation_ids": [

      ]
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 3,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

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/32 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": 32,
    "name": "Bauch Group",
    "sublocation_ids": [

    ],
    "devices": [
      {
        "name": "Water purifier 24",
        "token": "380397385778342267",
        "sku": "B000AF8T1C",
        "serial": "1fba997ae0a1ee3b"
      },
      {
        "name": "Blender 25",
        "token": "363331280370702299",
        "sku": "B00097DN12",
        "serial": "779247a76ce65dfb"
      }
    ]
  }
}

Fields

Users

View and update the users that have access to your account.

Listing account users

Retrieve a list of users belonging to your account. This list is paginated. For more information about interacting with paginated data, see Pagination.

Request

GET /api/rest/users HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

Endpoint

GET /api/rest/users

Response

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

{
  "data": [
    {
      "id": 31,
      "email": "nicolas.purdy@zulauflabadie.biz",
      "full_name": "Nicolas Purdy",
      "first_name": "Nicolas",
      "last_name": "Purdy",
      "current_login_at": "2019-09-09T03:20:53.000Z",
      "last_login_at": "2019-09-08T04:20:53.000Z",
      "last_request_at": "2019-09-09T04:20:53.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": "manager"
    },
    {
      "id": 32,
      "email": "schulist_terese@bergstromwalker.info",
      "full_name": "Terese Schulist",
      "first_name": "Terese",
      "last_name": "Schulist",
      "current_login_at": "2019-09-09T03:20:53.000Z",
      "last_login_at": "2019-09-02T04:20:53.000Z",
      "last_request_at": "2019-09-09T04:20:53.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": null
    },
    {
      "id": 33,
      "email": "felicitas_ernser@marquardtmcclure.biz",
      "full_name": "Felicitas Ernser",
      "first_name": "Felicitas",
      "last_name": "Ernser",
      "current_login_at": "2019-09-09T03:20:53.000Z",
      "last_login_at": "2019-09-02T04:20:53.000Z",
      "last_request_at": "2019-09-09T04:20:53.000Z",
      "time_zone": "Central Time (US & Canada)",
      "role": null
    }
  ],
  "meta": {
    "pagination": {
      "record_count": 3,
      "page_size": 25,
      "page_count": 1,
      "current_page": 1,
      "prev_page": null,
      "next_page": null
    }
  }
}

Fields

Updating an existing user

The User’s contact attributes can be updated.

Request

PATCH /api/rest/users/35 HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Content-Type: application/json

{
  "user": {
    "email": "hackett_harriet@kuvalis.com",
    "first_name": "Harriet",
    "last_name": "Hackett"
  }
}

Endpoint

PATCH /api/rest/users/:id

Parameters

Response

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

{
  "data": {
    "id": 35,
    "email": "hackett_harriet@kuvalis.com",
    "full_name": "Harriet Hackett",
    "first_name": "Harriet",
    "last_name": "Hackett",
    "current_login_at": "2019-09-09T03:20:54.000Z",
    "last_login_at": "2019-09-07T04:20:53.000Z",
    "last_request_at": "2019-09-09T04:20:54.000Z",
    "time_zone": "Central Time (US & Canada)",
    "role": null
  }
}

Fields

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/37 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

Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8

{
  "errors": [
    "Email should look like an email address.",
    "First name can't be blank"
  ]
}

Fields