Getting Started

BOX-EE platform is a cloud native, API-first application that allows users to interact with their BOX-EE devices using whatever client they feel most comfortable

The following sections are about specific API functionalities and limits. The best way to get familiar with the BOX-EE API is to use the OpenAPISpec docs.

Our endpoints are open to our registered users and are publicly documented using OpenAPISpec3 https://app.swaggerhub.com/apis-docs/epuerta9/box-ee-cloud/1.0.0

Box-ee API endpoint is api.box-ee.com/api/v1

To interact with our api, a signed JWT token within the X-Boxee-Auth header is needed.

After registering and verififying your email, the session_token can be aquired after a successful login request.

Make sure to specify Content-Type: application/json as part of the headers.

curl -X POST -d '{"email":"your-email", "password":"your-password"}' -H "Content-Type: application/json" https://api.box-ee.com/api/v1/self-service/login

{
  "msg": "string",
  "status_code": 0,
  "session_token": "string"
}

Requests can then be made to the protected endpoints.

Adding a device

curl -H "X-Boxee-Auth: your-session-token" -H "Content-Type: application/json" -d '{"device_name": "default", "device_type": "main"}' https://api.box-ee.com/api/v1/device | jq

{
  "device_id": "ba4759df-4787-4110-a744-1530da326a6d",
  "device_name": "default",
  "device_type": "main",
  "msg": "created",
  "status_code": 202
}

Listing all devices

curl -H "X-Boxee-Auth: your-token" -H "Content-Type: application/json" https://api.box-ee.com/api/v1/device/list | jq

{
  "count": 2,
  "devices": [
    {
      "health": 0,
      "id": "3ce8c153-cf07-4728-a1c2-efe5922872d2",
      "name": "first_device",
      "trackings": null,
      "type": "outdoor"
    },
    {
      "health": 0,
      "id": "ba4759df-4787-4110-a744-1530da326a6d",
      "name": "default",
      "trackings": null,
      "type": "main"
    }
  ],
  "msg": "found",
  "status_code": 200
}

Getting default device

Doing a GET on device endpoint (api.box-ee.com/api/v1/device) without query params, defaults to searching for a device named default. If you don’t have a default device, response code will be 400

curl -H "X-Boxee-Auth: your-token" -H "Content-Type: application/json" https://api.box-ee.com/api/v1/device | jq

{
  "health": "0",
  "msg": "found",
  "name": "default",
  "status_code": 200,
  "type": "main"
}