REST API (3.0.3)

Download OpenAPI specification:Download

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"

Fixtures

Butlr provides the ability to customize and design your space using all sorts of furniture, equipment or fixtures that help provide contextual information for spaces.

/api/v2/fixtures allows a user to interact with these elements.

List Fixture Types

Fixtures, such as furniture, equipment, appliances, etc. Use the "key" in other fixture-related endpoints, do not transform the "name" field to use in subsequent API requests; these values may change and are translated for use in i18n/l10n-friendly clients.

Authorizations:
query Parameters
lang
string
Default: "en-US"
Enum: "en-US" "pt-PT" "fr-FR"

Language code

Responses

Response Schema: application/json
required
Array of objects (FixtureType)
next
required
string (PaginationCursor)

Pagination cursor. Pass this as a query parameter to continue pagination.

prev
required
string (PaginationCursor)

Pagination cursor. Pass this as a query parameter to continue pagination.

Response samples

Content type
application/json
Example
{
  • "data": [
    • {
      • "key": "wall",
      • "name": "Wall"
      },
    • {
      • "key": "chair",
      • "name": "Chair"
      },
    • {
      • "key": "door",
      • "name": "Door"
      },
    • {
      • "key": "table",
      • "name": "Table"
      },
    • {
      • "key": "sofa",
      • "name": "Sofa"
      },
    • {
      • "key": "box",
      • "name": "Box"
      },
    • {
      • "key": "roundtable",
      • "name": "Round Table"
      },
    • {
      • "key": "sink",
      • "name": "Sink"
      },
    • {
      • "key": "toilet",
      • "name": "Toilet"
      },
    • {
      • "key": "bed",
      • "name": "Bed"
      }
    ],
  • "next": "",
  • "prev": ""
}

List Fixtures

List Fixtures in a Space

Authorizations:
path Parameters
space_id
required
string
Request Body schema: application/json
Array ()
center
required
Array of objects
local_id
required
number
rotation
required
number
scale
required
Array of objects
type
required
string non-empty

Responses

Response Schema: application/json
required
Array of objects non-empty unique
next
required
string
prev
required
string

Request samples

Content type
application/json
[
  • {
    • "type": "string",
    • "center": [
      • { }
      ],
    • "rotation": 0,
    • "scale": [
      • { }
      ],
    • "local_id": 0
    }
]

Response samples

Content type
application/json
{
  • "next": "",
  • "prev": "",
  • "data": [
    • {
      • "id": "fixture_1vMZWTSpylvm8rPkmkLWTsluX0S",
      • "type": "placeholdersensor",
      • "center": [
        • 49.84,
        • 22.49
        ],
      • "rotation": 90,
      • "scale": [
        • 1,
        • 1,
        • 1
        ]
      }
    ]
}

Add Fixture

Add Fixture

Authorizations:
path Parameters
space_id
required
string
Request Body schema: application/json
Array ()
center
required
Array of objects
rotation
required
number
scale
required
Array of objects
type
required
string non-empty

Responses

Request samples

Content type
application/json
[
  • {
    • "type": "string",
    • "center": [
      • { }
      ],
    • "rotation": 0,
    • "scale": [
      • { }
      ]
    }
]

Response samples

Content type
application/json
{
  • "message": "Invalid request"
}

Update Fixture

Update Fixture.

Authorizations:
path Parameters
fixture_id
required
string
space_id
required
string
Request Body schema: application/json

Update fixture

Array ()
center
Array of objects non-empty unique
rotation
number
scale
Array of objects non-empty unique
type
string non-empty

Responses

Response Schema: application/json
center
Array of objects
id
string non-empty
rotation
number
scale
Array of objects
type
string non-empty

Request samples

Content type
application/json
[
  • {
    • "type": "string",
    • "center": [
      • { }
      ],
    • "rotation": 0,
    • "scale": [
      • { }
      ]
    }
]

Response samples

Content type
application/json
[
  • {
    • "type": "string",
    • "center": [
      • { }
      ],
    • "rotation": 0,
    • "scale": [
      • { }
      ]
    }
]

Remove Fixture

Remove Fixture

Authorizations:
path Parameters
fixture_id
required
string
space_id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid request"
}

Get Fixture

Get Fixture information

Authorizations:
path Parameters
fixture_id
required
string
space_id
required
string

Responses

Response Schema: application/json
center
required
Array of objects
id
required
string non-empty
rotation
required
number
scale
required
Array of objects
type
required
string non-empty

Response samples

Content type
application/json
{
  • "id": "fixture_1vMZWTSpylvm8rPkmkLWTsluX0S",
  • "type": "desk",
  • "center": [
    • 49.84,
    • 22.49
    ],
  • "rotation": 90,
  • "scale": [
    • 1,
    • 1,
    • 1
    ]
}

Hives

The Butlr Hive is the device that connects Heatic sensors to our Butlr Infrastructure.

/api/v2/hives allows a user to activate, deactivate, or retrieve information about their hive(s).

List Hives

Get a list of hives

Authorizations:
query Parameters
details
string <binary>
Default: "false"
Enum: "true" "false"

detailed space/room/hive/sensor information

Responses

Response Schema: application/json
required
Array of objects (HiveRef) non-empty unique
next
required
string (PaginationCursor)

Pagination cursor. Pass this as a query parameter to continue pagination.

prev
required
string (PaginationCursor)

Pagination cursor. Pass this as a query parameter to continue pagination.

Response samples

Content type
application/json
Example
{
  • "next": "",
  • "prev": "",
  • "data": [
    • {
      • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "serial_number": "Home",
      • "num_sensors": 1
      }
    ]
}

Activate Hive

Active a hive

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "message": "Unauthorized"
}

Hive Details

Get Hive details

Authorizations:
path Parameters
hive_id
required
string

Responses

Response Schema: application/json
Array of objects (GatewayRef)
id
string
object (MqttInfo)
Array of objects (SensorRef)
serial_number
string
object (SpaceRef)

Reference to a Space

Response samples

Content type
application/json
{
  • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "serial_number": "100000000xxxxxxxxx",
  • "sensors": [
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "100000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 8.33,
        • 25.39
        ]
      }
    ],
  • "gateways": [
    • {
      • "id": "",
      • "mac_address": "",
      • "num_sensors": 0
      }
    ],
  • "space": {
    • "id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    • "name": "Home"
    },
  • "mqtt": {
    • "rc": 0,
    • "topics": { },
    • "broker_address": "",
    • "auth": { }
    }
}

Deactivate Hive

Deactivate a Hive

Authorizations:
path Parameters
hive_id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Unauthorized"
}

Update Hive

Update Hive

Authorizations:
path Parameters
hive_id
required
string

Responses

Response Schema: application/json
Array of objects (GatewayRef)
id
string
object (MqttInfo)
Array of objects (SensorRef)
serial_number
string
object (SpaceRef)

Reference to a Space

Response samples

Content type
application/json
{
  • "id": "hive_1pRIOg3Io7eYhgAqCacrOjAjgVO",
  • "serial_number": "febc53c8e685a722"
}

Rooms

Rooms are characterized as the physical location in which a sensor is placed that is described by a name such as bathroom or living room.

Many rooms take up a space as a way to provide further insight for users. Customizable and configurable through the Butlr Setup App.

List Room Types

List of room types. Use the "key" in other room-related endpoints, do not transform the "name" field to use in subsequent API requests; these values may change and are translated for use in i18n/l10n-friendly clients.

Authorizations:
query Parameters
lang
string
Default: "en-US"
Enum: "en-US" "pt-PT" "fr-FR"

Language code

Responses

Response Schema: application/json
required
Array of objects (RoomType)
next
required
string (PaginationCursor)

Pagination cursor. Pass this as a query parameter to continue pagination.

prev
required
string (PaginationCursor)

Pagination cursor. Pass this as a query parameter to continue pagination.

Response samples

Content type
application/json
Example
{
  • "data": [
    • {
      • "key": "entrance",
      • "name": "Entrance Hall"
      },
    • {
      • "key": "livingroom",
      • "name": "Living Room"
      },
    • {
      • "key": "diningroom",
      • "name": "Dining Room"
      },
    • {
      • "key": "bedroom",
      • "name": "Bedroom "
      },
    • {
      • "key": "bedroom2",
      • "name": "Second / Guest bedrooms"
      },
    • {
      • "key": "bathroom",
      • "name": "Bathroom"
      },
    • {
      • "key": "bathroom2",
      • "name": "Second / Guests' Bathroom"
      },
    • {
      • "key": "wc",
      • "name": "Small Bathroom/Washroom"
      },
    • {
      • "key": "kitchen",
      • "name": "Kitchen"
      },
    • {
      • "key": "pantry",
      • "name": "Pantry"
      },
    • {
      • "key": "storage",
      • "name": "Storage"
      },
    • {
      • "key": "closet",
      • "name": "Walk-in closets/Wardrobe"
      },
    • {
      • "key": "balcony",
      • "name": "Balcony"
      },
    • {
      • "key": "scullery",
      • "name": "Scullery"
      },
    • {
      • "key": "library",
      • "name": "Library"
      },
    • {
      • "key": "laundry",
      • "name": "Laundry Room"
      },
    • {
      • "key": "office",
      • "name": "Office"
      },
    • {
      • "key": "clearing",
      • "name": "Clearing"
      },
    • {
      • "key": "smokehouse",
      • "name": "Smokehouse"
      },
    • {
      • "key": "kitchenette",
      • "name": "Kitchennete / Bar"
      },
    • {
      • "key": "stairs",
      • "name": "Stairs"
      },
    • {
      • "key": "spa",
      • "name": "Spa"
      },
    • {
      • "key": "garbage",
      • "name": "Garbage Room"
      },
    • {
      • "key": "garage",
      • "name": "Garage"
      },
    • {
      • "key": "patio",
      • "name": "Patio"
      },
    • {
      • "key": "gym",
      • "name": "Gym"
      },
    • {
      • "key": "antechamber",
      • "name": "Antechamber"
      },
    • {
      • "key": "extcirculation",
      • "name": "External Circulation "
      },
    • {
      • "key": "intcirculation",
      • "name": "Internal Circulation "
      },
    • {
      • "key": "hall",
      • "name": "Hall"
      },
    • {
      • "key": "em",
      • "name": "Electromechanical Equipment Room"
      },
    • {
      • "key": "hyd",
      • "name": "Hydraulics Room"
      },
    • {
      • "key": "elevator",
      • "name": "Elevator"
      },
    • {
      • "key": "attic",
      • "name": "Attic"
      },
    • {
      • "key": "gamesroom",
      • "name": "Games Room"
      }
    ],
  • "next": "",
  • "prev": ""
}

List Rooms

List Rooms by Space

Authorizations:
path Parameters
space_id
required
string
query Parameters
details
string <binary>
Default: "false"
Enum: "true" "false"

detailed space/room/hive/sensor information

Responses

Response Schema: application/json
required
Array of objects non-empty unique
next
required
string
prev
required
string

Response samples

Content type
application/json
Example
{
  • "next": "",
  • "prev": "",
  • "data": [
    • {
      • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "type": "hotdesk",
      • "coordinates": [
        • [
          • 50.53,
          • 30.82
          ],
        • [
          • 62.8699951,
          • 30.82
          ],
        • [
          • 62.8699951,
          • 20.02
          ],
        • [
          • 50.53,
          • 20.02
          ]
        ],
      • "color": [
        • 255,
        • 0,
        • 0,
        • 255
        ],
      • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "name": "Hot Desks",
      • "maxCapacity": 0,
      • "area": 0,
      • "capacity": 14,
      • "mid_capacity": 7
      },
    • {
      • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "type": "phoneroom",
      • "coordinates": [
        • [
          • 38.535,
          • 23.21
          ],
        • [
          • 40.965,
          • 23.21
          ],
        • [
          • 40.965,
          • 21.71
          ],
        • [
          • 38.535,
          • 21.71
          ]
        ],
      • "color": [
        • 3,
        • 154,
        • 254,
        • 255
        ],
      • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "name": "Phone Room 1",
      • "maxCapacity": 0,
      • "area": 0,
      • "capacity": 1,
      • "mid_capacity": 1
      },
    • {
      • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "type": "confroom",
      • "coordinates": [
        • [
          • 42.325,
          • 26.34
          ],
        • [
          • 46.715,
          • 26.34
          ],
        • [
          • 46.715,
          • 23.32
          ],
        • [
          • 42.325,
          • 23.32
          ]
        ],
      • "color": [
        • 26,
        • 0,
        • 255,
        • 255
        ],
      • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "name": "Conference Room 1",
      • "maxCapacity": 0,
      • "area": 0,
      • "capacity": 0,
      • "mid_capacity": 0
      }
    ]
}

Create Room

Add a Room to a Space

Authorizations:
path Parameters
space_id
required
string
Request Body schema:

Create a room and add it to a space.

Array ()
color
Array of objects
Array of objects
height
number
name
string non-empty
type
string non-empty

Responses

Response Schema: application/json
Array ()
required
Array of objects
id
required
string non-empty
name
required
string non-empty
type
required
string non-empty
area
number
capacity
number
color
Array of objects
door_line
number
in_direction
number
maxCapacity
number
mid_capacity
number
parallel_to_door
number
sensitivity
number
sensors
Array of objects
object

Request samples

Content type
[
  • {
    • "name": "string",
    • "type": "string",
    • "height": 0,
    • "color": [
      • { }
      ],
    • "coordinates": [
      • {
        • "0": [
          • { }
          ],
        • "1": [
          • { }
          ],
        • "2": [
          • { }
          ],
        • "3": [
          • { }
          ]
        }
      ]
    }
]

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "type": "string",
    • "name": "string",
    • "coordinates": [
      • {
        • "0": [
          • { }
          ],
        • "1": [
          • { }
          ],
        • "2": [
          • { }
          ],
        • "3": [
          • { }
          ]
        }
      ],
    • "sensors": [
      • { }
      ],
    • "color": [
      • { }
      ],
    • "space": {
      • "id": "string",
      • "name": "string"
      },
    • "maxCapacity": 0,
    • "area": 0,
    • "capacity": 0,
    • "mid_capacity": 0,
    • "door_line": 0,
    • "parallel_to_door": 0,
    • "in_direction": 0,
    • "sensitivity": 0
    }
]

Room Details

Get Room details

Authorizations:
path Parameters
room_id
required
string
space_id
required
string
query Parameters
details
string

true

Responses

Response Schema: application/json
coordinates
required
Array of Array of numbers (Polygon)
id
required
string non-empty
required
Array of objects (SensorRef)
type
required
string non-empty

A "key" from GET /room-types

color
Array of integers <int32> (Color) [ 3 .. 4 ] items

RGBA Color represented as list of length 4, e.g., white=[255, 255, 255, 255], black=[0, 0, 0, 255]. If the alpha value (index 3) is not set, it will default to 255 (opaque)

height
number
object (SpaceRef)

Reference to a Space

Response samples

Content type
application/json
{
  • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "type": "hotdesk",
  • "name": "Hot Desks",
  • "coordinates": [
    • [
      • 50.53,
      • 30.82
      ],
    • [
      • 62.8699951,
      • 30.82
      ],
    • [
      • 62.8699951,
      • 20.02
      ],
    • [
      • 50.53,
      • 20.02
      ]
    ],
  • "sensors": [
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 53.329998,
        • 28.83
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 53.0399971,
        • 25.93
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 60.8599968,
        • 29.1199989
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 57.5,
        • 23.05
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 53.0399971,
        • 23.05
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_1vKOHytUVfLcuIKEKuh5JEuODfS",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3.5,
      • "center": [
        • 61.42,
        • 25.21
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3.5,
      • "center": [
        • 61.42,
        • 22.63
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 57.21,
        • 24.85
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 57.5,
        • 28.6199989
        ]
      }
    ],
  • "color": [
    • 255,
    • 0,
    • 0,
    • 255
    ],
  • "space": {
    • "id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    • "name": ""
    },
  • "maxCapacity": 0,
  • "area": 0,
  • "capacity": 14,
  • "mid_capacity": 7
}

Update Room

Update a Room

Authorizations:
path Parameters
room_id
required
string
space_id
required
string
Request Body schema: application/json

Update a room

Array ()
color
required
Array of objects non-empty unique
required
Array of objects non-empty unique
height
required
number
name
required
string non-empty
type
required
string non-empty

Responses

Response Schema: application/json
area
required
number
capacity
required
number
color
required
Array of objects
required
Array of objects
id
required
string non-empty
maxCapacity
required
number
mid_capacity
required
number
name
required
string non-empty
required
Array of objects non-empty unique
required
object
type
required
string non-empty

Request samples

Content type
application/json
[
  • {
    • "name": "string",
    • "type": "string",
    • "height": 0,
    • "color": [
      • { }
      ],
    • "coordinates": [
      • {
        • "0": [
          • { }
          ],
        • "1": [
          • { }
          ],
        • "2": [
          • { }
          ],
        • "3": [
          • { }
          ]
        }
      ]
    }
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "name": "string",
  • "coordinates": [
    • {
      • "0": [
        • { }
        ],
      • "1": [
        • { }
        ],
      • "2": [
        • { }
        ],
      • "3": [
        • { }
        ]
      }
    ],
  • "sensors": [
    • {
      • "id": "string",
      • "mac_address": "string",
      • "name": "string",
      • "mode": "string",
      • "isEntrance": true,
      • "hive": {
        • "id": "string",
        • "serial_number": "string"
        },
      • "room": {
        • "id": "string",
        • "space_id": "string"
        },
      • "gateway_id": "string",
      • "height": 0,
      • "center": [
        • { }
        ]
      }
    ],
  • "color": [
    • { }
    ],
  • "space": {
    • "id": "string",
    • "name": "string"
    },
  • "maxCapacity": 0,
  • "area": 0,
  • "capacity": 0,
  • "mid_capacity": 0
}

Delete Room

Delete a Room

Authorizations:
path Parameters
room_id
required
string
space_id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Unauthorized"
}

Sensors

Butlr Heatic Sensor that captures thermal data (C°) in an 8x8 grid of temperature values at an adjustable frequency.

List Sensors

List sensors

Authorizations:
query Parameters
details
string <binary>
Default: "false"
Enum: "true" "false"

detailed space/room/hive/sensor information

Responses

Response Schema: application/json
required
Array of objects (SensorRef) non-empty unique
next
required
string (PaginationCursor)

Pagination cursor. Pass this as a query parameter to continue pagination.

prev
required
string (PaginationCursor)

Pagination cursor. Pass this as a query parameter to continue pagination.

Response samples

Content type
application/json
Example
{
  • "data": [
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "Bathroom",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 44.71,
        • 25
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "Conference Room",
      • "mode": "activity",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 44.71,
        • 21.32
        ]
      }
    ]
}

Sensor Details

Sensor details

Authorizations:
path Parameters
sensor_id
required
string

Sensor Id or MAC Address

Responses

Response Schema: application/json
coordinates
required
Array of numbers <float> (Point) 2 items

A 2D XY coordinate, e.g., origin=[0.0, 0.0]

height
required
number
required
object (HiveRef)
id
required
string non-empty
mac_address
required
string (MacAddress) ^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

MAC Address. The standard (IEEE 802) format for printing MAC-48 addresses in human-friendly form is six groups of two hexadecimal digits, separated by hyphens - or colons :.

mode
required
string (SensorMode)
Enum: "activity" "headcount" "repeater"

Configuration that determines how the sensor collects data.

  • headcount is optimized for directional traffic where detections can be used for counting entries/exits (doorway, hallway, corridor)

  • activity is optimized for capturing movement and presence in an area without a specific direction (room, lobby, lounge)

  • repeater does not collect data. It is used to boost the wireless mesh network of either the headcount or activity sensor(s)

orientation
required
Array of numbers <float> (Orientation) 3 items

Yaw, pitch, roll [0.0., 0.0, 0.0] (unit: degrees)

required
object (RoomRef)

Reference to Room

required
object (SpaceRef)

Reference to a Space

activeHours
Array of numbers 7 items

The number of hours the sensor is active, indexed by days of the week. Zero-indexed starting on Sunday.

door_line
number

distance from the door line. Does not apply to repeater sensors

object (GatewayRef)

Reference to a Gateway

in_direction
number

is the sensor in the direction of the door. Does not apply to repeater sensors

isEntrace
boolean

is the sensor monitoring an entrace. Does not apply to repeater sensors

parallel_to_door
boolean

is the sensor parallel to the door. Does not apply to repeater sensors

sensitivity
number

sensor's sensitivity. Does not apply to repeater sensors

Response samples

Content type
application/json
{
  • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "mac_address": "00-17-0d-00-00-xx-xx-xx",
  • "name": "",
  • "mode": "activity",
  • "isEntrance": false,
  • "hive": {
    • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    • "serial_number": "10000000xxxxxxxx"
    },
  • "space": {
    • "id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    • "name": "Home"
    },
  • "room": {
    • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
  • "orientation": [
    • 0,
    • 0,
    • 0
    ],
  • "height": 3,
  • "center": [
    • 44.71,
    • 25
    ],
  • "gateway": {
    • "id": "",
    • "mac_address": ""
    },
  • "activeHours": [
    • 24,
    • 24,
    • 24,
    • 24,
    • 24,
    • 24,
    • 24
    ],
  • "door_line": 0,
  • "sensitivity": 0.5,
  • "parallel_to_door": true,
  • "in_direction": 0
}

Update Sensor

Update sensor attributes

Authorizations:
path Parameters
sensor_id
required
string

Sensor Id or MAC Address

Request Body schema:
object

Responses

Response Schema: application/json
required
Array of objects non-empty unique

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "string",
      • "mac_address": "string",
      • "name": "string",
      • "mode": "string",
      • "isEntrance": true,
      • "hive": {
        • "id": "string",
        • "serial_number": "string"
        },
      • "room": {
        • "id": "string",
        • "space_id": "string"
        },
      • "gateway_id": "string",
      • "height": 0,
      • "center": [
        • { }
        ]
      }
    ]
}

Deactivate Sensor

Deactivate a Sensor

Authorizations:
path Parameters
sensor_id
required
string

Sensor Id or MAC Address

Responses

Response samples

Content type
application/json
{
  • "message": "Unauthorized"
}

Spaces

The physical space corresponding to one or more hives. A space is made up of one or more rooms and is customizable and configurable through the Butlr Setup App.

List Spaces

List spaces

Authorizations:
query Parameters
details
string <binary>
Default: "false"
Enum: "true" "false"

detailed space/room/hive/sensor information

Responses

Response Schema: application/json
required
Array of objects non-empty unique
next
required
string
prev
required
string

Response samples

Content type
application/json
Example
{
  • "data": [
    • {
      • "id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "name": "Company_Location_1",
      • "address": "",
      • "capacity": 10,
      • "mid_capacity": 5,
      • "area": 0,
      • "timezone": "",
      • "installation_date": "",
      • "sensors": [
        • {
          • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
          • "mac_address": "00-17-0d-00-00-xx-xx-xx",
          • "name": "",
          • "mode": "headcount",
          • "isEntrance": false,
          • "hive": {
            • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
            • "serial_number": "10000000xxxxxxxx"
            },
          • "room": {
            • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
            • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
            },
          • "gateway_id": "",
          • "height": 3,
          • "center": [
            • 49.84,
            • 14.19
            ]
          },
        • {
          • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
          • "mac_address": "00-17-0d-00-00-xx-xx-xx",
          • "name": "",
          • "mode": "headcount",
          • "isEntrance": false,
          • "hive": {
            • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
            • "serial_number": "10000000xxxxxxxx"
            },
          • "room": {
            • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
            • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
            },
          • "gateway_id": "",
          • "height": 3,
          • "center": [
            • 44.1499977,
            • 14.87
            ]
          },
        • {
          • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
          • "mac_address": "00-17-0d-00-00-xx-xx-xx",
          • "name": "",
          • "mode": "headcount",
          • "isEntrance": false,
          • "hive": {
            • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
            • "serial_number": "10000000xxxxxxxx"
            },
          • "room": {
            • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
            • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
            },
          • "gateway_id": "",
          • "height": 3,
          • "center": [
            • 20.06,
            • 14.87
            ]
          }
        ],
      • "hives": [
        • {
          • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
          • "serial_number": "10000000xxxxxxxx",
          • "num_sensors": 3
          }
        ],
      • "rooms": [
        • {
          • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
          • "type": "office",
          • "coordinates": [
            • [
              • 17,
              • 27.5
              ],
            • [
              • 47,
              • 27.5
              ],
            • [
              • 47,
              • 12.5
              ],
            • [
              • 17,
              • 12.5
              ]
            ],
          • "color": [
            • 0,
            • 255,
            • 127,
            • 255
            ],
          • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
          • "name": "Office",
          • "maxCapacity": 0,
          • "area": 0,
          • "capacity": 0,
          • "mid_capacity": 0,
          • "door_line": 0,
          • "parallel_to_door": 0,
          • "in_direction": 0,
          • "sensitivity": 0
          },
        • {
          • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
          • "type": "confroom",
          • "coordinates": [
            • [
              • 47,
              • 22.5
              ],
            • [
              • 57,
              • 22.5
              ],
            • [
              • 57,
              • 12.5
              ],
            • [
              • 47,
              • 12.5
              ]
            ],
          • "color": [
            • 0,
            • 255,
            • 127,
            • 255
            ],
          • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
          • "name": "Conference Room",
          • "maxCapacity": 0,
          • "area": 0,
          • "capacity": 0,
          • "mid_capacity": 0,
          • "door_line": 0,
          • "parallel_to_door": 0,
          • "in_direction": 0,
          • "sensitivity": 0
          }
        ],
      • "gateways": [
        • {
          • "id": "",
          • "mac_address": ""
          }
        ]
      },
    • {
      • "id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "name": "Company_Location_2",
      • "address": "",
      • "capacity": 0,
      • "mid_capacity": 0,
      • "area": 0,
      • "timezone": "",
      • "installation_date": "",
      • "sensors": [ ],
      • "hives": [ ],
      • "rooms": [ ],
      • "gateways": [
        • {
          • "id": "",
          • "mac_address": ""
          }
        ]
      }
    ],
  • "next": "",
  • "prev": ""
}

Create Space

Create a Space

Authorizations:
Request Body schema: application/json
name
string

Responses

Response Schema: application/json
id
required
string
name
required
string

Request samples

Content type
application/json
{
  • "name": "794 Odie Knolls"
}

Response samples

Content type
application/json
{
  • "id": "space_1pIbIwxksdfxorqxfHfFgcJYgef",
  • "name": "794 Odie Knolls"
}

Space Details

Get Space details

Authorizations:
path Parameters
space_id
required
string
query Parameters
details
string <binary>
Default: "false"
Enum: "true" "false"

detailed space/room/hive/sensor information

Responses

Response Schema: application/json
address
required
string
area
required
number
capacity
required
number
required
Array of objects non-empty unique
required
Array of objects non-empty unique
id
required
string non-empty
installation_date
required
string
mid_capacity
required
number
name
required
string non-empty
required
Array of objects non-empty unique
required
Array of objects non-empty unique
timezone
required
string

Response samples

Content type
application/json
{
  • "id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "name": "Company_Location_1",
  • "address": "",
  • "capacity": 10,
  • "mid_capacity": 5,
  • "area": 0,
  • "timezone": "",
  • "installation_date": "",
  • "sensors": [
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "headcount",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 49.84,
        • 14.19
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "headcount",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 44.1499977,
        • 14.87
        ]
      },
    • {
      • "id": "sensor_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "mac_address": "00-17-0d-00-00-xx-xx-xx",
      • "name": "",
      • "mode": "headcount",
      • "isEntrance": false,
      • "hive": {
        • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "serial_number": "10000000xxxxxxxx"
        },
      • "room": {
        • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
        • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
      • "gateway_id": "",
      • "height": 3,
      • "center": [
        • 20.06,
        • 14.87
        ]
      }
    ],
  • "hives": [
    • {
      • "id": "hive_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "serial_number": "10000000xxxxxxxx",
      • "num_sensors": 3
      }
    ],
  • "rooms": [
    • {
      • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "type": "office",
      • "coordinates": [
        • [
          • 17,
          • 27.5
          ],
        • [
          • 47,
          • 27.5
          ],
        • [
          • 47,
          • 12.5
          ],
        • [
          • 17,
          • 12.5
          ]
        ],
      • "color": [
        • 0,
        • 255,
        • 127,
        • 255
        ],
      • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "name": "Office",
      • "maxCapacity": 0,
      • "area": 0,
      • "capacity": 0,
      • "mid_capacity": 0,
      • "door_line": 0,
      • "parallel_to_door": 0,
      • "in_direction": 0,
      • "sensitivity": 0
      },
    • {
      • "id": "room_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "type": "confroom",
      • "coordinates": [
        • [
          • 47,
          • 22.5
          ],
        • [
          • 57,
          • 22.5
          ],
        • [
          • 57,
          • 12.5
          ],
        • [
          • 47,
          • 12.5
          ]
        ],
      • "color": [
        • 0,
        • 255,
        • 127,
        • 255
        ],
      • "space_id": "space_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      • "name": "Conference Room",
      • "maxCapacity": 0,
      • "area": 0,
      • "capacity": 0,
      • "mid_capacity": 0,
      • "door_line": 0,
      • "parallel_to_door": 0,
      • "in_direction": 0,
      • "sensitivity": 0
      }
    ],
  • "gateways": [
    • {
      • "id": "",
      • "mac_address": ""
      }
    ]
}

Update Space

Update a space.

Authorizations:
path Parameters
space_id
required
string
Request Body schema: application/json

Update a space or add a sensor

address
required
string non-empty
area
required
number
capacity
required
number
required
Array of objects non-empty unique
required
Array of objects non-empty unique
id
required
string non-empty
installation_date
required
string
mid_capacity
required
number
name
required
string non-empty
required
Array of objects non-empty unique
required
Array of objects non-empty unique
timezone
required
string non-empty

Responses

Response Schema: application/json
address
required
string non-empty
area
required
number
capacity
required
number
required
Array of objects non-empty unique
required
Array of objects non-empty unique
id
required
string non-empty
installation_date
required
string
mid_capacity
required
number
name
required
string non-empty
required
Array of objects non-empty unique
required
Array of objects non-empty unique
timezone
required
string non-empty

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "address": "string",
  • "capacity": 0,
  • "mid_capacity": 0,
  • "area": 0,
  • "timezone": "string",
  • "installation_date": "string",
  • "sensors": [
    • {
      • "deleted_at": "string",
      • "generation": 0,
      • "isEntrance": true,
      • "auto_calibration_end": 0,
      • "activeHours": [
        • { }
        ],
      • "orientation": [
        • { }
        ],
      • "name": "string",
      • "center": [
        • { }
        ],
      • "hive_serial": "string",
      • "SK": "string",
      • "id": "string",
      • "remainingBatteryDays": 0,
      • "mac_address": "string",
      • "model": "string",
      • "lastBatteryChange": "string",
      • "in_direction": 0,
      • "entity_type": "string",
      • "client_id": "string",
      • "mode": "string",
      • "auto_calibration_start": 0,
      • "autoCalibratedAt": "string",
      • "sensitivity": 0,
      • "hive_id": "string",
      • "door_line": 0,
      • "height": 0,
      • "remainingBatteryPercent": 0,
      • "parallel_to_door": true,
      • "auto_calibration_person": 0,
      • "space_id": "string",
      • "PK": "string",
      • "room_id": "string",
      • "isBatteryLow": "string"
      }
    ],
  • "hives": [
    • {
      • "id": "string",
      • "serial_number": "string",
      • "num_sensors": 0
      }
    ],
  • "rooms": [
    • {
      • "capacity": 0,
      • "deleted_at": "string",
      • "entity_type": "string",
      • "client_id": "string",
      • "autoCalibratedAt": "string",
      • "mid_capacity": 0,
      • "name": "string",
      • "sensors": [
        • {
          • "room_id": "string",
          • "door_line": 0,
          • "last_heartbeat": 0,
          • "client_id": "string",
          • "mode": "string",
          • "mac_address": "string",
          • "SK": "string",
          • "model": "string",
          • "id": "string",
          • "remainingBatteryPercent": 0,
          • "height": 0,
          • "generation": 0,
          • "isEntrance": true,
          • "orientation": [
            • { }
            ],
          • "parallel_to_door": true,
          • "activeHours": [
            • { }
            ],
          • "center": [
            • { }
            ],
          • "in_direction": 0,
          • "hive_id": "string",
          • "deleted_at": "string",
          • "entity_type": "string",
          • "remainingBatteryDays": 0,
          • "lastBatteryChange": "string",
          • "name": "string",
          • "hive_serial": "string",
          • "isBatteryLow": "string",
          • "PK": "string",
          • "sensitivity": 0,
          • "space_id": "string",
          • "autoCalibratedAt": "string"
          }
        ],
      • "maxCapacity": 0,
      • "area": 0,
      • "space": {
        • "name": "string",
        • "id": "string"
        },
      • "SK": "string",
      • "PK": "string",
      • "id": "string",
      • "color": [
        • { }
        ],
      • "coordinates": [
        • {
          • "0": [
            • { }
            ],
          • "1": [
            • { }
            ],
          • "2": [
            • { }
            ],
          • "3": [
            • { }
            ]
          }
        ],
      • "type": "string"
      }
    ],
  • "gateways": [
    • {
      • "id": "string",
      • "mac_address": "string"
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "address": "string",
  • "capacity": 0,
  • "mid_capacity": 0,
  • "area": 0,
  • "timezone": "string",
  • "installation_date": "string",
  • "sensors": [
    • {
      • "deleted_at": "string",
      • "generation": 0,
      • "isEntrance": true,
      • "auto_calibration_end": 0,
      • "activeHours": [
        • { }
        ],
      • "orientation": [
        • { }
        ],
      • "name": "string",
      • "center": [
        • { }
        ],
      • "hive_serial": "string",
      • "SK": "string",
      • "id": "string",
      • "remainingBatteryDays": 0,
      • "mac_address": "string",
      • "model": "string",
      • "lastBatteryChange": "string",
      • "in_direction": 0,
      • "entity_type": "string",
      • "client_id": "string",
      • "mode": "string",
      • "auto_calibration_start": 0,
      • "autoCalibratedAt": "string",
      • "sensitivity": 0,
      • "hive_id": "string",
      • "door_line": 0,
      • "height": 0,
      • "remainingBatteryPercent": 0,
      • "parallel_to_door": true,
      • "auto_calibration_person": 0,
      • "space_id": "string",
      • "PK": "string",
      • "room_id": "string",
      • "isBatteryLow": "string"
      }
    ],
  • "hives": [
    • {
      • "id": "string",
      • "serial_number": "string",
      • "num_sensors": 0
      }
    ],
  • "rooms": [
    • {
      • "capacity": 0,
      • "deleted_at": "string",
      • "entity_type": "string",
      • "client_id": "string",
      • "autoCalibratedAt": "string",
      • "mid_capacity": 0,
      • "name": "string",
      • "sensors": [
        • {
          • "room_id": "string",
          • "door_line": 0,
          • "last_heartbeat": 0,
          • "client_id": "string",
          • "mode": "string",
          • "mac_address": "string",
          • "SK": "string",
          • "model": "string",
          • "id": "string",
          • "remainingBatteryPercent": 0,
          • "height": 0,
          • "generation": 0,
          • "isEntrance": true,
          • "orientation": [
            • { }
            ],
          • "parallel_to_door": true,
          • "activeHours": [
            • { }
            ],
          • "center": [
            • { }
            ],
          • "in_direction": 0,
          • "hive_id": "string",
          • "deleted_at": "string",
          • "entity_type": "string",
          • "remainingBatteryDays": 0,
          • "lastBatteryChange": "string",
          • "name": "string",
          • "hive_serial": "string",
          • "isBatteryLow": "string",
          • "PK": "string",
          • "sensitivity": 0,
          • "space_id": "string",
          • "autoCalibratedAt": "string"
          }
        ],
      • "maxCapacity": 0,
      • "area": 0,
      • "space": {
        • "name": "string",
        • "id": "string"
        },
      • "SK": "string",
      • "PK": "string",
      • "id": "string",
      • "color": [
        • { }
        ],
      • "coordinates": [
        • {
          • "0": [
            • { }
            ],
          • "1": [
            • { }
            ],
          • "2": [
            • { }
            ],
          • "3": [
            • { }
            ]
          }
        ],
      • "type": "string"
      }
    ],
  • "gateways": [
    • {
      • "id": "string",
      • "mac_address": "string"
      }
    ]
}

Delete Space

Delete a Space

Authorizations:
path Parameters
space_id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Unauthorized"
}

Zones

List Zones

List Zones by Space

Authorizations:
path Parameters
space_id
required
string

Responses

Response Schema: application/json
Array of objects (Zone)
next
string
prev
string

Response samples

Content type
application/json
{
  • "next": "string",
  • "prev": "string",
  • "data": [
    • {
      • "id": "string",
      • "type": "string",
      • "name": "string",
      • "color": [
        • 0
        ],
      • "coordinates": [
        • 0
        ],
      • "space_id": "string",
      • "area": 0,
      • "area_unit": "string",
      • "capacity": 0,
      • "mid_capacity": 0,
      • "room_id": "string"
      }
    ]
}

Create Zone

Add a Zone to a Space

Authorizations:
path Parameters
space_id
required
string
Request Body schema: application/json
Array ()
area
integer
capacity
integer
color
Array of integers
coordinates
Array of integers
mid_capacity
integer
name
string
type
string

Responses

Response Schema: application/json
Array ()
area
integer
area_unit
string
capacity
integer
color
Array of integers
coordinates
Array of integers
id
string
mid_capacity
integer
name
string
room_id
string
space_id
string
type
string

Request samples

Content type
application/json
No sample

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "type": "string",
    • "name": "string",
    • "color": [
      • 0
      ],
    • "coordinates": [
      • 0
      ],
    • "space_id": "string",
    • "area": 0,
    • "area_unit": "string",
    • "capacity": 0,
    • "mid_capacity": 0,
    • "room_id": "string"
    }
]

Zone Details

Get Zone Details

Authorizations:
path Parameters
space_id
required
string
zone_id
required
string

Responses

Response Schema: application/json
area
integer
area_unit
string
capacity
integer
color
Array of integers
coordinates
Array of integers
id
string
mid_capacity
integer
name
string
room_id
string
space_id
string
type
string

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "name": "string",
  • "color": [
    • 0
    ],
  • "coordinates": [
    • 0
    ],
  • "space_id": "string",
  • "area": 0,
  • "area_unit": "string",
  • "capacity": 0,
  • "mid_capacity": 0,
  • "room_id": "string"
}

Update Zone

Update Zone

Authorizations:
path Parameters
space_id
required
string
zone_id
required
string
Request Body schema: application/json
area
integer
capacity
integer
color
Array of integers
coordinates
Array of integers
mid_capacity
integer
name
string

Responses

Response Schema: application/json
area
integer
area_unit
string
capacity
integer
color
Array of integers
coordinates
Array of integers
id
string
mid_capacity
integer
name
string
room_id
string
space_id
string
type
string

Request samples

Content type
application/json
{
  • "name": "string",
  • "color": [
    • 0
    ],
  • "coordinates": [
    • 0
    ],
  • "area": 0,
  • "capacity": 0,
  • "mid_capacity": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "name": "string",
  • "color": [
    • 0
    ],
  • "coordinates": [
    • 0
    ],
  • "space_id": "string",
  • "area": 0,
  • "area_unit": "string",
  • "capacity": 0,
  • "mid_capacity": 0,
  • "room_id": "string"
}

Delete Zone

Delete a Zone

Authorizations:
path Parameters
space_id
required
string
zone_id
required
string

Responses

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

Users

Get User Preferences

Gets the user preferences

Authorizations:

Responses

Response Schema: application/json
language
string

Response samples

Content type
application/json
{
  • "language": "en-US"
}

Update User Preferences

Updates the user preferences.

Authorizations:
Request Body schema: application/json
language
required
string

Responses

Response Schema: application/json
language
string

Request samples

Content type
application/json
{
  • "language": "zh-Hans"
}

Response samples

Content type
application/json
{
  • "language": "zh-Hans"
}

Resources

List Supported Languages

Gets the list of supported languages.

Responses

Response Schema: application/json
default
string
object

Response samples

Content type
application/json
{
  • "default": "en-US",
  • "languages": {
    • "en-US": "English (United States)",
    • "zh-Hans": "Chinese (Simplified)"
    }
}

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:
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
{
  • "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
      }
    }
}

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

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:
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": [
    • {
      • "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
          ]
        ]
      }
    ]
}