butlr logo
Documentation Powered by ReDoc

REST API (3.0.3)

Download OpenAPI specification:Download

Butlr Support: support@butlr.io URL: https://support.butlr.io/hc/en-us License: Unlicensed Terms of Service

Latest Notice of Deprecation

v2 APIs v2/spaces, v2/hives, v2/sensors, and all subresources of these 3 endpoints will reach its end-of-life on Friday, October 11th, 2024. PLEASE NOTE ALL LOGIN, REPORTING, and DETECTIONS endpoints will remain functional. All listed endpoints will continue to be supported!

Fixtures as an object and subresource of floors (formerly known as spaces) will reach its end-of-life on Friday, September 20th, 2024. There is no replacement functionality for this as it was a feature of our previous installation tool, also deprecated early in 2024.

GraphQL

Documentation: https://docs.butlr.io/graphql

We would like to inform you that a large portion of our APIs will eventually be deprecated in favor of Butlr's new GraphQL API. We kindly request you to please refer to the documentation available at https://docs.butlr.io/graphql for the GraphQL schema.

We believe that this transition to GraphQL will be a significant improvement for our users. GraphQL provides a more efficient and flexible way of querying data from the server compared to traditional REST APIs. With GraphQL, you can specify exactly what data you need and receive only that data, reducing the amount of data transfer and improving the overall performance of your application.

In addition, GraphQL allows for easier versioning of APIs. As your application evolves, you can modify the GraphQL schema without breaking existing client code, enabling you to make changes to your backend without disrupting your users.

We encourage you to start migrating to our new GraphQL API and explore the benefits it has to offer. If you have any questions or concerns, please don't hesitate to contact our support team.

Getting Started:

FAQ

Release Notes

Developer Guide

Postman Collection

The butlr API (v2) is organized around REST. The API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Identifiers

Primary Identifiers

Resources always have a primary identifier which is the resource type followed by an underscore and a random alpha-numeric string generated by the API at creation time:

Examples:

  • sensor_1pSzBqzDXWA1W0orILZbfTA71Ak
  • hive_1pSzJPFUdkjraoJeqMz2wEWSfX8
  • space_1pSzKM2HKhSHsZ2vBclvMFrUKcZ

Secondary Identifiers

Some resource types have additional secondary identifiers. Sensors can also be looked up using their MAC Address, while Hives can be identified by their serial number (printed on the device).

Examples:

  • 00-60-2F-57-04-BC - sensor Address
  • 65fefe57f497d2f6 - hive serial number

The Butlr Heatic Sesnor is a battery-powered unit which captures thermal data and sends it to the Hive via local wireless mesh network.

A Butlr Hive is the "base station" of our system. The Hive is the intermediary between the sensors (which communicate on a local mesh network) and Butlr services. Butlr Heatic Sensors connect to the Hive, which passes the sensor data via the internet to the Butlr ecosystem.

Authentication

Bearer Token

Authentication and authorization uses JWT's (https://jwt.io/introduction).

Client Credentials Grant

Learn about OAuth2.0 Client Credentials Grant

1. Sign in with your client id and secret.

curl --location --request POST 'https://api.butlr.io/api/v2/clients/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "audience": "https://butlrauth/",
    "grant_type": "client_credentials"
}'

NOTE: If you don't know your CLIENT_ID and CLIENT_SECRET, please reach out to support@butlr.io

2. Use the access_token field in the response to hit the Butlr API.

curl --request GET \
  --url https://api.butlr.io/api/v2/spaces \
  --header 'Authorization: Bearer {access_token}'

For example, if the access token is abc.123.def the request should be

curl --request GET \
  --url https://api.butlr.io/api/v2/spaces \
  --header 'Authorization: Bearer abc.123.def'

3. Renew the token.

Unlike some other OAuth2.0 flows, the Client Credentials flow does not provide a refresh token. Simply repeat Step 1 and 2 to get a new token. We suggest you avoid doing this on every request to prevent performance issues and throttling.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Login

User Login

User login password grant flow. This API will return the set of tokens (access_token, id_token, refresh_token) given a proper username & password.

Request Body schema: application/json
password
required
string <password>
username
required
string <email>

Responses

Response Schema: application/json
access_token
string
expires_in
number
id_token
string
refresh_token
string
scope
string
token_type
string

Request samples

Content type
application/json
{
  • "username": "your_email@butlr.io",
  • "password": "123!"
}

Response samples

Content type
application/json
{
  • "access_token": "adksiek******.***********.********",
  • "refresh_token": "v1.************",
  • "id_token": "3904fjkd********.******.*****",
  • "scope": "openid email profile offline_access",
  • "expires_in": 86400,
  • "token_type": "Bearer"
}

Refresh Token

Given a proper refresh_token and client_id, you will get back an new set of access_token / refresh_token / id_token. Call this API when your access_token has expired.

Request Body schema: application/json

The client_id can be found inside the access_token.azp claim.

client_id
required
string
refresh_token
required
string

Responses

Response Schema: application/json
access_token
string
expires_in
integer
id_token
string
refresh_token
string
scope
string
token_type
string

Request samples

Content type
application/json
{
  • "refresh_token": "v1.MlbvM7oBuuAlsbsaf23asdfasdf234asdfgk-ggae89oikjasdfLFKJDFH",
  • "client_id": "c9023dlDKLFJKPdckspoek229KJD"
}

Response samples

Content type
application/json
{
  • "access_token": "adksiek******.***********.********",
  • "refresh_token": "v1.************",
  • "id_token": "3904fjkd********.******.*****",
  • "scope": "openid email profile offline_access",
  • "expires_in": 86400,
  • "token_type": "Bearer"
}

Clients

Client Login (M2M)

M2M Client Authentication Endpoint

Accepts ClientID, Client Secret, Audience, and GrantType exactly as auth0's oauth/token endpoint does.

Returns AccessToken, ExpiresIn, Scope, and Token Type

Authorizations:
Bearer Token
Request Body schema: application/json

POST /clients/login Request Body

audience
string
client_id
string
client_secret
string
grant_type
string

Responses

Response Schema: application/json
access_token
string
expires_in
integer
scope
string
token_type
string

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "audience": "string",
  • "grant_type": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "scope": "string",
  • "expires_in": 0,
  • "token_type": "string"
}

Reporting

Reporting

The /reporting endpoint is only accessible via api/v3.

Customize data aggregation by filtering (filter), grouping order (group_by) and results aggregation time window (window).

Authorizations:
Bearer Token
Request Body schema: application/json
required
object
object
object
object

Responses

Response Schema: application/json
data
object
Array of objects

Request samples

Content type
application/json
Example
Aggregate all occupants by all spaces for the last 1 day
Aggregate all occupants by all spaces for the last 1 day
Aggregate all occupants by all sensors for the last 30 days
Aggregate all occupants by time for the last week
{
  • "group_by": {
    • "order": [
      • "space_id",
      • "field"
      ]
    },
  • "window": {
    • "every": "5m",
    • "function": "max"
    },
  • "filter": {
    • "start": "-1d"
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "occupancy": {
      • "sum": 26,
      • "min": 1,
      • "max": 3,
      • "count": 12,
      • "mean": 2.1666666666666665,
      • "median": 3,
      • "stddev": 0.7993052538854533
      }
    }
}

Detections

Detections

Returns historical detection points per sensor mac_address given a period of time and an interval window. Within an interval window, a data point will be returned based on specified function.

Note:

  • Replacement for /streams api that has been deprecated
  • Only accessible in /v3
Authorizations:
Bearer Token
Request Body schema: application/json
data_types
required
Array of strings
Items Enum: "detections_local" "detections_world" "heatmap"
required
object
object

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "data_types": [
    • "detections_local"
    ],
  • "filter": {
    • "start": "string",
    • "stop": "string",
    • "omit_empty_value": true,
    • "space_id": "string",
    • "room_id": "string",
    • "mac_addresses": [
      • "string"
      ]
    },
  • "window": {
    • "every": "string",
    • "function": "string"
    }
}

Response samples

Content type
application/json
Example
detections_local
detections_local
detections_world
occupancy
heatmap
{
  • "detections_local": [
    • {
      • "start_time": 1667888615000,
      • "sample_time": 1667888615900,
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "value": [
        • [
          • 0.38257575757575757,
          • 0.4242424242424242
          ],
        • [
          • 0.5625,
          • 0.9375
          ]
        ]
      },
    • {
      • "start_time": 1667888615000,
      • "sample_time": 1667888615900,
      • "mac_address": "00-17-0d-11-11-xx-xx-xx",
      • "value": [
        • [
          • 0.345,
          • 0.678
          ]
        ]
      }
    ]
}