NAV
shell javascript

Introduction


// More information available on our github page at
// https://github.com/littlebits/cloud-client-api-http

npm install --save @littlebits/cloud-http

Welcome to the litteBits Cloud API! You can use our API to access litteBits Cloud API endpoints to manage your cloudbits.

We have language bindings in Shell and Javascript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This example API documentation page was created with Slate. Feel free to edit it and use it as a base for your own API’s documentation.

Rate limiting

The littleBits Cloud API is rate limited to prevent abuse that would degrade our ability to maintain consistent API performance for all users. By default, each API key or app is rate limited at 1800 requests per hour. If your requests are being rate limited, HTTP response code 429 will be returned with an rate_limit_exceeded error.

Authentication

To authorize, use this code:

var api = require('littlebits-cloud-http')
      .defaults({ access_token: 'meowmeowmeow' })
# With shell, you can just pass the correct header with each request
curl "https://api-http.littlebitscloud.cc" \
  -H "Authorization: Bearer meowmeowmeow"

Make sure to replace meowmeowmeow with your API key.

litteBits uses API keys to allow access to the API. You get you API key at our cloud control.

littleBits expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer meowmeowmeow

Devices

Get All Your Devices

api.devices()
curl "https://api-http.littlebitscloud.cc/v2/devices" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

[
    {
        "label": "my cloudbit 1",
        "id": "00e040000001",
        "user_id": 1,
        "is_connected": false,
        "subscriptions":[
            {
                "publisher_id": "00e040000002",
                "subscriber_id": "00e040000001",
                "publisher_events":[
                    {
                        "name": "amplitude"
                    }
                ]
            },
        {
                "publisher_id": "00e040000001",
                "subscriber_id": "https://YOURSERVER/endpoint",
                "publisher_events":[
                    {
                        "name": "amplitude:delta:ignite"
                    }
                ]
            }
        ],
        "subscribers": [
        ],
        "input_interval_ms": 750
    },
    {
        "label": "my cloudbit 2",
        "id": "00e040000002",
        "user_id": 1,
        "is_connected": false,
        "subscriptions": [
        ],
        "subscribers":[
            {
                "publisher_id": "00e040000002",
                "subscriber_id": "00e040000001",
                "publisher_events": [
                    {
                        "name": "amplitude"
                    }
                ]
            }
        ],
        "input_interval_ms":750
    }
]

Get a Specific Device

api.devices('00e040000001')
curl "https://api-http.littlebitscloud.cc/v2/devices/00e040000001" \
  -H "Authorization: meowmeowmeow"

The above command returns JSON structured like this:

{
        "label": "my cloudbit 1",
        "id": "00e040000001",
        "user_id": 1,
        "is_connected": false,
        "subscriptions":[
            {
                "publisher_id": "00e040000002",
                "subscriber_id": "00e040000001",
                "publisher_events":[
                    {
                        "name": "amplitude"
                    }
                ]
            },
        {
                "publisher_id": "00e040000001",
                "subscriber_id": "https://YOURSERVER/endpoint",
                "publisher_events":[
                    {
                        "name": "amplitude:delta:ignite"
                    }
                ]
            }
        ],
        "subscribers": [
        ],
        "input_interval_ms": 750
}

This endpoint retrieves a specific device.

Update Device Settings

curl "https://api-http.littlebitscloud.cc/v2/devices/00e040000001" \
  -X PUT \
  -H "Authorization: meowmeowmeow" \
  -H "Content-type: application/json" \
  -d '{ "update": { "label": "cloudbit", "input_interval_ms": 250 } }'

This endpoint updates a specific device.

HTTP Request

PUT https://api-http.littlebitscloud.cc/v2/devices/<ID>

URL Parameters

Parameter Description
ID The ID of the device to update

JSON Payload

Parameter Description
label The new label for this device. Default is “cloudbit”
input_interval_ms Interval in milliseconds when input is read and broadcast. Default is 250 and the minimum is 200.

Output voltage on device

api.ouput({ device_id: 00e040000001, percent: 100, duration_ms: 3000 }
curl "https://api-http.littlebitscloud.cc/v2/devices/00e040000001/output" \
  -X POST \
  -H "Authorization: meowmeowmeow" \
  -H "Content-type: application/json" \
  -d '{ "percent": 100, "duration_ms": 3000 }'

This endpoint outputs voltage on a device.

HTTP Request

POST https://api-http.littlebitscloud.cc/v2/devices/<ID>/output

URL Parameters

Parameter Description
ID The ID of the device to send output to

JSON Payload

Parameter Description
percent A percent of the maximum current output between 0 and 100. Default is 100.
duration_ms Output will be sustained for the given milliseconds. If duration_ms is -1 it will last forever or until another ouput is received by device. Maximum is 32000 and default is 3000 (3 seconds).

Subscriptions

Create subscription

Use this endpoint to create a subscription between devices or to receive events in a HTTP server that you control.

api.subscribe({ publisher_id: 00e040000001, subscriber_id: 00e040000002 })

api.subscribe({ publisher_id: 00e040000001, subscriber_id: 00e040000002 })

api.subscribe({
    publisher_id: 00e040000001,
    subscriber_id: 00e040000002,
    publisher_events: ['amplitude']
})
curl "https://api-http.littlebitscloud.cc/v2/subscriptions" \
  -X POST \
  -H "Authorization: meowmeowmeow" \
  -H "Content-type: application/json" \
  -d '{ "publisher_id": "00e040000001" ,"subscriber_id": "00e040000002" }'

curl "https://api-http.littlebitscloud.cc/v2/subscriptions" \
  -X POST \
  -H "Authorization: meowmeowmeow" \
  -H "Content-type: application/json" \
  -d '{ "publisher_id": "00e040000001" ,"subscriber_id": "http://YOURSERVER/endpoint" }'

curl "https://api-http.littlebitscloud.cc/v2/subscriptions" \
  -X POST \
  -H "Authorization: meowmeowmeow" \
  -H "Content-type: application/json" \
  -d '{ "publisher_id": "00e040000001" ,"subscriber_id": "00e040000002", "publisher_events: "['amplitude']" }'

The above command returns the JSON that was POSTed.

{
    "publisher_id": "00e040000001",
    "subscriber_id": "00e040000002",
    "publisher_events": ["amplitude"]
}

HTTP Request

POST https://api-http.littlebitscloud.cc/v2/subscriptions

JSON Payload

Parameter Description
publisher_id Device id of publisher.
subscriber_id Device id or callback URI. You must ensure that URI is accessible to the Internet.
publisher_events Events to subscribe to. Defaults to [“amplitude:delta:ignite”]

Available events to subscribe to.

Event Description
amplitude when there is any voltage (catch-all, default)
amplitude:delta:sustain when high voltage is constant (eg button being held)
amplitude:delta:ignite when there is significant voltage jump (eg button press)
amplitude:delta:release when there is significant voltage drop (eg button release)
amplitude:delta:nap when low voltage is constant (eg idle bitSnap system)
amplitude:level:active generic, when there is high voltage (eg during a sustain or maybe just ignited)
amplitude:level:idle generic, when there is low voltage (eg during a long nap or maybe just released)

List subscriptions

api.subscriptions({ publisher_id: "00e040000001" })

api.subscriptions({ subscriber_id: "00e040000002" })

api.subscriptions({ publisher_id: "00e040000001", subscriber_id: "00e040000002" })


curl "https://api-http.littlebitscloud.cc/v2/subscriptions?publisher_id=00e040000001" \
  -H "Authorization: Bearer meowmeowmeow"

curl "https://api-http.littlebitscloud.cc/v2/subscriptions?subscriber_id=00e040000002" \
  -H "Authorization: Bearer meowmeowmeow"

curl "https://api-http.littlebitscloud.cc/v2/subscriptions?publisher_id=00e040000001&subscriber_id=00e040000002" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

[
    {
        "publisher_id": "00e040000001",
        "subscriber_id":"00e040000002",
        "publisher_events":["amplitude"]
    },
    {
        "publisher_id": "00e040000001",
        "subscriber_id": "https://YOURSERVER/endpoint",
        "publisher_events":["amplitude:delta:ignite"]
    }
]

HTTP Request

GET https://api-http.littlebitscloud.cc/v2/subscriptions?publisher_id=<ID>&subscriber_id=<ID or HTTP endpoint>

Request Parameters

Parameter Description
publisher_id List subscriptions where given device is a publisher
subscriber_id List subscriptions where given device is a subscriber. It can be a device ID or a callback URI.

You can provide publisher_id, subscriber_id or both.

Delete a Subscription

Remove a subscription between a publisher and a subscriber.

curl "https://api-http.littlebitscloud.cc/v2/subscriptions" \
  -X DELETE \
  -H "Authorization: meowmeowmeow" \
  -H "Content-type: application/json" \
  -d '{ "publisher_id": "00e040000001" ,"subscriber_id": "http://YOURSERVER/endpoint" }'

HTTP Request

DELETE https://api-http.littlebitscloud.cc/v2/subscriptions

JSON Payload

Parameter Description
subscriber_id Device id or callback URI.
publisher_id Device id of publisher.

Errors

Error Code Meaning
400 Bad Request – Your request is badly formed
401 Unauthorized – Your API key is wrong
403 Forbidden – You do not have permission to access that device
404 Not Found – The specified device could not be found
405 Method Not Allowed – You tried to access a device with an invalid method
406 Not Acceptable – You requested a format that isn’t json
429 Too Many Requests – You’re requesting too many kittens! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.