Introduction

Welcome to the littleBits Mobile Application API reference docs. The littleBits.cc website itself has two existing API architecture’s:

One used and exposed primarily through the SpreeCommerce OpenSource framework
another primarily used and exposed for littleBits CloudControl.

API Responses

Standard Response format

{
    "results": {
        "value": "{what you asked for here}"
    },
    "meta": {
        "version": 2,
        "criteria": {
            "method": "{method used}",
            "endpoint": "/api/v2/{endpoint}",
            "params": [
                {
                "name": "{param}",
                "value": "{value}"
                }
            ]
        },
        "success": true,
        "errors": "{error message if success false}"
    }
}

LB API Response Format

Every response will be an object with two keys, results and meta. Results will be an object or array of objects depending on the end point. Or empty if there was an error. Meta describes the request you made.

version - Number, What API version you are using.
criteria - Object, How we processed your request.
- method - String, What HTTP method was used.
- endpoint - String, What endpoint you hit.
- params - Array of Objects, An array of key-value objects that represent what the values for your params were, including optional ones you might not have specified.
success - Boolean, if the request was successfully processed.
errors - String, the error message associated with a false success value.

Documentation Format

Authentication

To request a user’s authorization token, use this code:

curl --data "mobile_app[email]=you@example.com&mobile_app[password]=savekittens"
https://{server_name}/api/v2/session/create

The above command returns JSON structured like this:

  {
    "results":{
      "id":64651,
      "username":"someguy",
      "twitter":null,
      "location":null,
      "bio":null,
      "image":"https://lb-community-staging.s3.amazonaws.com/uploads/user/avatar/medium_pinkModule.png",
      "member_since":"Member since June 2015",
      "spree_api_key":"abc123",
      "projects":[]
    },
    "meta":{
      "version":2.0,
      "criteria":{
        "method":"POST",
        "endpoint":"/api/v2/session/create",
        "params":[
          {
            "name":"email",
            "value":"e@ma.il"
          }
        ]
      },
      "success":true,
      "errors":null
    }
  }

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "MobileAppAuth: {mobile_auth_token}"

Testing on Staging Servers

While testing on Staging servers (stg1,stg2, pre-live, etc.) most requests are protected via HTTP Basic Auth. Therefore each HTTP Request must be prefaced with username/password like:

username:password@stg1.littlebits.cc

username:password@pre-live.littlebits.cc

HTTP Request

POST http://{server}/api/v2/session/create

Form Data

Parameter	Description
mobile_app[email]	End user’s email address
mobile_app[password]	End users’ password

The API uses keys to grant access. A users mobile authentication token is returned in response to successful email and password authentication.

The API expects mobile authentication token to be included in subseqeunt API requests in a header that looks like the following:

MobileAppAuth: meowmeowmeow

POST http://{server}/api/v2/session/fb

curl https://{server_name}/api/v2/session/fb

Expects the following minimum payload:

  {
    "first_name": "Peter",
    "last_name": "Pan",
    "email": "e2@ma.il",
    "access_token": {
      "userID": "2"
    }
  }

Log out

curl --data "token=savekittens"
https://{server_name}/api/v2/session/destroy

The above command always returns 204 no content status

HTTP Request

POST http://{server}/api/v2/session/destroy

Form Data

Parameter	Description
token	`mobile_auth_token`

Content

GET Content

To request CMS content, use this code:

curl -X GET https://{server_name}/api/v2/content?key="{your_content_key_here}"

The above command returns JSON. We currently support two types of display responses: list and html.

List

{
    "results": {
        "display": "list",
        "content": [
            {
            "name": "power",
            "values": {
                "title": "It All Begins With Power",
                "value": "It's kind of important",
                "image": "https://lb-community.s3.amazonaws.com/uploads/image/asset/9531/card_feature_IMG_4778_-_Copy.JPG"
                }
            },
            {
            "name": "light",
            "values": {
                "title": "All Of The Lights",
                "value": "All of them!",
                "image": "https://lb-community.s3.amazonaws.com/uploads/image/asset/5953/large_filled_Sweater_IMG_7021LR.jpg"
                }
            }
        ]
    },
    "meta": {
        "version": 2,
        "criteria": {
            "method": "GET",
            "endpoint": "/api/v2/content",
            "params": [
                {
                "name": "key",
                "value": "learn.lbbasics"
                }
            ]
        },
        "success": true,
        "errors": null
    }
}

HTML

{
    "results": {
        "display": "html",
        "content": "<div class=\"container section-divider\">\ <h2 class=\"title-md section-title\">How it <strong class=\"purple\">Works</strong></h2>\ <div class=\"row\">\ <div class=\"\">\ <p class=\"section-sub-title\">The library has over 60 modules and growing. Every module works with every other in millions of combinations, you will never run out of things to make. Thousands of people are already inventing with littleBits. Join us!</p>\ </div></div></div>"
        },
    "meta": {
        "version": 2,
        "criteria": {
            "method": "GET",
            "endpoint": "/api/v2/content",
            "params": [
                    {
                    "name": "key",
                    "value": "learn.play"
                    }
                ]
            },
        "success": true,
        "errors": null
    }
}

Getting CMS Content

In order to retieve content from our server you will need a key. Keys are dot separated strings that allow for the creation of content that is simulateously structured and namespaced. An example is:

content.landingpages.podcasts.android

.android represents an instance of podcasts, while the key .podcasts respresents all of the podcast instances.

Responses

Every response object will have two keys: display and content. Currently, we support two types of display types: html and list. List is an array of json objects that respresent the items you requested. HTML is a block of HTML to display.

Current Keys

Currently we only have to live keys as samples learn.lbbasics will return you a list of lbbasics objects. learn.play will return a blob of html to be rendered.

My Library

GET all modules

curl http://<SERVER>/api/v2/my_library --user <HTTPUSER>:<HTTPPASSWORD> -H "MobileAppAuth: <USER_API_KEY>"

JSON Response:

{
  "results": [
    {
      "variant_id": 216,
      "product_id": 201,
      "quantity": 2,
      "title": "cloudBit™",
      "description": "The cloudBit is the easiest way to create internet-connected devices. You can now snap the internet to anything!",
      "type": "Bit",
      "bit_type": "wire",
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2403/large/Cloud_1LR.jpg?1423168706",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2404/large/Cloud_2LR.jpg?1423168709",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2405/large/cloud_diagram2.png?1423168711"
      ]
    },
    {
      "variant_id": 13,
      "product_id": 13,
      "quantity": 1,
      "title": "usb power",
      "description": "<strong>SHORT DESCRIPTION</strong><br>The USB power may be the smallest in the series, but it's big enough to send juice to all your creations. Connect",
      "type": "Bit",
      "bit_type": "power",
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1333/large/IMG_8500RFLXLR.jpg?1423166105",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1463/large/usbpower.jpg?1423166319",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1622/large/IMG_9861LR.jpg?1423166419",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2111/large/ProductImages_USBPower.jpg?1423167809"
      ]
    },
    {
      "variant_id": 179,
      "product_id": 166,
      "quantity": 5,
      "title": "USB Power Adapter + Cable",
      "description": "This power adapter and USB cable combo is the perfect way to  power permanent creations! Simply connect the cable from the wall adapter to your",
      "type": "Accessory",
      "bit_type": null,
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2250/large/WallAdapter_1LR.jpg?1423168338",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2251/large/WallAdapter_2LR.jpg?1423168341"
      ]
    },
    {
      "variant_id": 186,
      "product_id": 173,
      "quantity": 2,
      "title": "cloudBit module",
      "description": "The cloudBit is the easiest way to create internet-connected devices. You can now snap the internet to anything! Retrofit your thermostat to control i",
      "type": "Bit",
      "bit_type": null,
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2252/large/Cloud_1LR.jpg?1423168344",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2253/large/Cloud_2LR.jpg?1423168348"
      ]
    }
  ],
  "meta": {
    "version": 2,
    "criteria": {
      "method": "GET",
      "endpoint": "/api/v2/my_library",
      "params": null
    },
    "success": true,
    "errors": null
  }
}

This endpoint shows all modules in a user’s library

HTTP Request

GET http://{server}/api/v2/my_library

CREATE new module

 curl -X POST -d variant_id=216 http://<SERVER>/api/v2/my_library --user <HTTPUSER>:<HTTPPASSWORD> -H "MobileAppAuth: <USER_API_KEY>"

JSON Response:

{
  "results": [
    {
      "variant_id": 13,
      "product_id": 13,
      "quantity": 1,
      "title": "usb power",
      "description": "<strong>SHORT DESCRIPTION</strong><br>The USB power may be the smallest in the series, but it's big enough to send juice to all your creations. Connect",
      "type": "Bit",
      "bit_type": "power",
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1333/large/IMG_8500RFLXLR.jpg?1423166105",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1463/large/usbpower.jpg?1423166319",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1622/large/IMG_9861LR.jpg?1423166419",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2111/large/ProductImages_USBPower.jpg?1423167809"
      ]
    },
    {
      "variant_id": 179,
      "product_id": 166,
      "quantity": 4,
      "title": "USB Power Adapter + Cable",
      "description": "This power adapter and USB cable combo is the perfect way to  power permanent creations! Simply connect the cable from the wall adapter  <a href",
      "type": "Accessory",
      "bit_type": null,
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2250/large/WallAdapter_1LR.jpg?1423168338",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2251/large/WallAdapter_2LR.jpg?1423168341"
      ]
    },
    {
      "variant_id": 186,
      "product_id": 173,
      "quantity": 1,
      "title": "cloudBit module",
      "description": "The cloudBit is the easiest way to create internet-connected devices. You can now snap the internet to anything! Retrofit your thermostat to control i",
      "type": "Bit",
      "bit_type": null,
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2252/large/Cloud_1LR.jpg?1423168344",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2253/large/Cloud_2LR.jpg?1423168348"
      ]
    },
    {
      "variant_id": 216,
      "product_id": 201,
      "quantity": 1,
      "title": "cloudBit™",
      "description": "The cloudBit is the easiest way to create internet-connected devices. You can now snap the internet to anything!",
      "type": "Bit",
      "bit_type": "wire",
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2403/large/Cloud_1LR.jpg?1423168706",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2404/large/Cloud_2LR.jpg?1423168709",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2405/large/cloud_diagram2.png?1423168711"
      ]
    }
  ],
  "meta": {
    "version": 2,
    "criteria": {
      "method": "POST",
      "endpoint": "/api/v2/my_library",
      "params": [
        {
          "name": "variant_id",
          "value": "216"
        }
      ]
    },
    "success": true,
    "errors": null
  }
}

This endpoint creates a Library Module based on a product’s variant_id, adds it the user’s library with a quantity of 1, and returns the added Library Module(s).

NOTE: If the variant_id is for a kit, then all bit variants that belong to that kit will be added to the user’s library and returned in the JSON structure as well.

HTTP Request

POST http://<SERVER>/api/v2/my_library

The following parameters should be passed as form data:

Parameter	Type	Description
variant_id	integer	The ID of the product variant you are adding the user’s library

UPDATE existing module

NOTE: The following example is for incrementing the quantity of a kit Library Module (with variant_id=216) that already exists with a quantity of 2 in the user’s library. This will return more than one Library Module that represent the bits contained within the kit.

 curl -X PUT -d variant_id=216 -d operator="add" -d delta=1 http://<SERVER>/api/v2/my_library --user <HTTPUSER>:<HTTPPASSWORD> -H "MobileAppAuth: <USER_API_KEY>"

JSON Response:

{
  "results": [
    {
      "variant_id": 13,
      "product_id": 13,
      "quantity": 3,
      "title": "usb power",
      "description": "<strong>SHORT DESCRIPTION</strong><br>The USB power may be the smallest in the series, but it's big enough to send juice to all your creations. Connect",
      "type": "Bit",
      "bit_type": "power",
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1333/large/IMG_8500RFLXLR.jpg?1423166105",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1463/large/usbpower.jpg?1423166319",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/1622/large/IMG_9861LR.jpg?1423166419",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2111/large/ProductImages_USBPower.jpg?1423167809"
      ]
    },
    {
      "variant_id": 179,
      "product_id": 166,
      "quantity": 5,
      "title": "USB Power Adapter + Cable",
      "description": "This power adapter and USB cable combo is the perfect way to  power permanent creations! Simply connect the cable from the wall adapter to your",
      "type": "Accessory",
      "bit_type": null,
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2250/large/WallAdapter_1LR.jpg?1423168338",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2251/large/WallAdapter_2LR.jpg?1423168341"
      ]
    },
    {
      "variant_id": 186,
      "product_id": 173,
      "quantity": 3,
      "title": "cloudBit module",
      "description": "The cloudBit is the easiest way to create internet-connected devices. You can now snap the internet to anything! Retrofit your thermostat to control i",
      "type": "Bit",
      "bit_type": null,
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2252/large/Cloud_1LR.jpg?1423168344",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2253/large/Cloud_2LR.jpg?1423168348"
      ]
    },
    {
      "variant_id": 216,
      "product_id": 201,
      "quantity": 3,
      "title": "cloudBit™",
      "description": "The cloudBit is the easiest way to create internet-connected devices. You can now snap the internet to anything!",
      "type": "Bit",
      "bit_type": "wire",
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2403/large/Cloud_1LR.jpg?1423168706",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2404/large/Cloud_2LR.jpg?1423168709",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2405/large/cloud_diagram2.png?1423168711"
      ]
    }
  ],
  "meta": {
    "version": 2,
    "criteria": {
      "method": "PUT",
      "endpoint": "/api/v2/my_library",
      "params": [
        {
          "name": "variant_id",
          "value": "216"
        },
        {
          "name": "delta",
          "value": "1"
        },
        {
          "name": "operator",
          "value": "add"
        }
      ]
    },
    "success": true,
    "errors": null
  }
}

This endpoint updates a Library Module based on a product’s variant_id. It will either add or subtract a Library Module from the user’s library, based on the delta and operator parameters it is given.

NOTE: If the variant_id belongs to a kit, then all bit variants that belong to that kit will be added to or subtracted from the user’s library and returned in a JSON structure as well.

HTTP Request

PUT http://<SERVER>/api/v2/my_library

The following parameters should be passed as form data:

Parameter	Type	Description
variant_id	integer	The ID of the product variant you are adding the user’s library
operator	string	Either “add” or “subtract”.
delta	integer	The quantity that you wish to add or subtract (must be positive)

DELETE module

  curl -X DELETE -d variant_id=216 http://<SERVER>/api/v2/my_library --user <HTTPUSER>:<HTTPPASSWORD> -H "MobileAppAuth: <USER_API_KEY>"

JSON Response:

{
  "results": [
    {
      "variant_id": 179,
      "product_id": 166,
      "quantity": 2,
      "title": "USB Power Adapter + Cable",
      "description": "This power adapter and USB cable combo is the perfect way to  power permanent creations! Simply connect the cable from the wall adapter to your",
      "type": "Accessory",
      "bit_type": null,
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2250/large/WallAdapter_1LR.jpg?1423168338",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2251/large/WallAdapter_2LR.jpg?1423168341"
      ]
    },
    {
      "variant_id": 201,
      "product_id": 185,
      "quantity": 3,
      "title": "MaKey MaKey",
      "description": "Visit the <a href=\\\"http://littlebits.cc/bitlab\\\">bitLab </a> to reserve your module!\\\r\\\n\\\r\\\nThe MaKey MaKey turns everyday objects into touchpads and combin",
      "type": "Bit",
      "bit_type": "wire",
      "images": [
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2328/large/MakeMakey_Module_6337LR.jpg?1423168548",
        "https://s3.amazonaws.com/lb-spree-staging/spree/products/2330/large/makeymakey4.JPG?1423168551"
      ]
    }
  ],
  "meta": {
    "version": 2,
    "criteria": {
      "method": "DELETE",
      "endpoint": "/api/v2/my_library",
      "params": [
        {
          "name": "variant_id",
          "value": "216"
        }
      ]
    },
    "success": true,
    "errors": null
  }
}

This endpoint deletes a Library Module from the user’s library and returns all the remaining modules in the user’s library.

NOTE: If the variant_id is for a kit, then all bit variants that belong to that kit will be deleted based on the quantity of the kit.

HTTP Request

DELETE http://<SERVER>/api/v2/my_library

The following parameters should be passed as form data:

Parameter	Type	Description
variant_id	integer	The ID of the product variant you are adding the user’s library

Product and Variants

GET All Products

To request all products with all of it’s variants and images, use this code:

curl -X GET https://{server_name}/api/v2/products"

To request the a product with all of it’s variants and images, use this code:

Example

{
  "results": [
    {
      "id": 1,
      "name": "fan",
      "type": "Bit",
      "bit_type": "output",
      "bit_variant_ids": [],
      "description": "The fan Bit is just what you'd think: a small electric fan tethered to a littleBits module. It's great for those hot summer nights. Use our little fan to create fluttering movement in your creations or just to keep yourself cool.\\\r\\\n\\\r\\\nCheck out our <b> <a href=\\\"http://littlebits.cc/tips-tricks-the-fan-bit\\\" target=\\\"_blank\\\">Tips + Tricks</a></b> for more ideas on using the fan.",
      "slug": "fan",
      "available_on": "2012-12-17T00:00:00.000Z",
      "updated_at": "2015-06-17T20:21:48.000Z",
      "short_description": "The fan Bit is just what you'd think: a small electric fan tethered to a littleBits module. It's great for those hot summer nights. Use our little fan ",
      "inactive": false,
      "variants": [
        {
          "id": 1,
          "type": "Bit",
          "bit_type": "output",
          "is_master": true,
          "images": [
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/1353/product/IMG_8722RFLXLR.jpg?1423166165",
              "position": 1,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/1439/product/fan.jpg?1423166254",
              "position": 2,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/1648/product/Fan.gif?1423166521",
              "position": 3,
              "type": "image/gif"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2082/product/ProductImages_Fan.jpg?1423167715",
              "position": 4,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2220/product/Bit_Card_50_o13_Fan.jpg?1423168255",
              "position": 5,
              "type": "image/jpeg"
            }
          ],
          "kit_bits": []
        }
      ]
    },
    {
      "id": 198,
      "name": "Arduino Coding Kit",
      "type": "Kit",
      "bit_type": null,
      "bit_variant_ids": [
        137,
        136,
        138,
        83,
        25,
        26,
        42
      ],
      "description": "<strong>YOU BRING THE CODE. <br> \\\r\\\nWE'LL BRING THE ELECTRONICS. </strong><br>\\\r\\\n<br>\\\r\\\n<p>This kit contains 8 of our favorite prototyping modules. It’s everything you need to get started with electronics and programming. \\\r\\\n\\\r\\\nMake your own Etch-a-Sketch&#153;! Program a visual display! We’ll walk you through the basics using the Arduino programming environment, without the breadboarding, soldering or wiring normally required. Perfect for hackers, designers, makers and tinkerers of all levels. </p> \\\r\\\n<br>\\\r\\\n<li>Includes everything you need to get started (battery + power included!) right out of the box</li>\\\r\\\n<li>Build with 8 Getting Started sketches, including a DIY Etch-a-Sketch&#153;, Mouse Control and hundreds more from Arduino’s community!</li>\\\r\\\n<li>Communicate with software (Processing, MaxMSP, Flash etc…)</li>\\\r\\\n<li>Snap modules easily to 3 inputs and 3 outputs on the Arduino module, as well as additional I/O for advanced hardware interaction</li>\\\r\\\n<li>Access to community support from Arduino AND littleBits</li>\\\r\\\n<br>\\\r\\\n\\\r\\\nThe Arduino module is also available individually <strong><a href=\\\"http://littlebits.cc/bits/arduino/\\\">here</a> </strong>.\\\r\\\n\\\r\\\n<hr>\\\r\\\n<b>GETTING STARTED\\\r\\\n<li><a href=\\\"http://discuss.littlebits.cc/t/getting-started-with-arduino/109\\\"_blank\\\">Forums</a></li>\\\r\\\n<li><a href=\\\"http://littlebits.cc/tips-tricks-arduino-module\\\" target=\\\_blank\\\">Tips + Tricks</a></li></b>",
      "slug": "arduino-coding-kit",
      "available_on": "2014-11-09T00:00:00.000Z",
      "updated_at": "2015-06-17T20:26:37.000Z",
      "short_description": "Contains 8 modules to get you started with electronics and programming.",
      "inactive": false,
      "variants": [
        {
          "id": 213,
          "type": "Kit",
          "bit_type": null,
          "is_master": true,
          "images": [
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2484/product/ACK-kit-bits_LR.jpg?1423169038",
              "position": 0,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2492/product/jpeg.jpg?1423169057",
              "position": 1,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2507/product/arduinodiagram2.jpg?1423169092",
              "position": 2,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2488/product/Screenshot_2014-11-25_14.53.08.png?1423169042",
              "position": 3,
              "type": "image/png"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2491/product/Screenshot_2014-11-25_18.16.58.png?1423169053",
              "position": 4,
              "type": "image/png"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2509/product/diyetch.jpg?1423169095",
              "position": 5,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2506/product/arduino_screensaver.jpg?1423169089",
              "position": 6,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2510/product/pong.jpg?1423169098",
              "position": 7,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2402/product/ArduinoStarterKit_HR_Photoshopped-rgb.jpg?1423168694",
              "position": 8,
              "type": "image/jpeg"
            },
            {
              "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2410/product/arduino-kit.png?1423168763",
              "position": 9,
              "type": "image/png"
            }
          ],
          "kit_bits": [
            {
              "variant_id": 152,
              "product_id": 139,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 101,
              "product_id": 101,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 40,
              "product_id": 40,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 38,
              "product_id": 38,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 29,
              "product_id": 29,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 24,
              "product_id": 24,
              "quantity": 2,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 23,
              "product_id": 23,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 22,
              "product_id": 22,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 21,
              "product_id": 21,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:32.000Z"
            },
            {
              "variant_id": 51,
              "product_id": 51,
              "quantity": 1,
              "updated_at": "2015-06-15T18:41:36.000Z"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "version": 2,
    "criteria": {
      "method": "GET",
      "endpoint": "/api/v2/products",
      "params": [
        {}
      ]
    },
    "success": true,
    "errors": null
  }
}

Return

This returns all active or retired product with all of their variants and their associated images.

Note:

Kit products will have a bit_variant_ids node with all bit variant id’s that are inside the kit within their JSON structure.
Bit products have a bit_type node.
All products have a type node

GET Product

To request the a product with all of it’s variants and images, use this code:

curl -X GET https://{server_name}/api/v2/products/{:id}"

The above command returns JSON.

Example

{
    "results": {
        "id": 4,
        "name": "slide dimmer",
         "type": "Bit",
        "bit_type": "input",
        "description": "You control the slide dimmer Bit by moving its lever from one end of the Bit to the other. It functions just like a light dimmer you might find at home, or a volume fader in a recording studio. Follow it with an LED for some adjustable mood lighting.\ \ \ \ Check out our <b> <a href=\"http://littlebits.cc/fridays-tips-tricks-the-slide-dimmer-and-dimmer-bits\" target=\"_blank\">Tips + Tricks</a></b> for more ideas on using the slide dimmer.",
        "slug": "slide-dimmer",
        "available_on": "2012-12-16T00:00:00.000Z",
        "updated_at": "2015-05-11T16:54:46.000Z",
        "short_description": "You control the slide dimmer Bit by moving its lever from one end of the Bit to the other. It functions just like a light dimmer you might find at home",
        "cost": 0,
        "inactive": false,
        "variants": [
            {
                "id": 4,
                "is_master": true,
                "type": "Bit",
                "bit_type": "input",
                "images": [
                    {
                    "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/1349/product/IMG_8529RFLXLR.jpg?1423166155",
                    "position": 1,
                    "type": "image/jpeg"
                    },
                    {
                    "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/1458/product/slidedimmer.jpg?1423166301",
                    "position": 2,
                    "type": "image/jpeg"
                    }
                ]
            }
        ]
    },
    "meta": {
    "version": 2,
    "criteria": {
        "method": "GET",
        "endpoint": "/api/v2/products/85",
        "params": [
            {
            "name": "product_id",
            "value": "85"
            }
        ]
    },
    "success": true,
    "errors": null
    }
}

Return

This returns a product with all of it’s variants and their associated images.

GET Variant

To request the a variant of a product and all of its images, use this code:

curl -X GET https://{server_name}/api/v2/products/{:product_id}/variants/{:id}"

The above command returns JSON.

Example

{
    "results": {
        "id": 4,
        "type": "Bit",
        "bit_type": "input",
        "is_master": true,
        "images": [
            {
            "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/1349/product/IMG_8529RFLXLR.jpg?1423166155",
            "position": 1,
            "type": "image/jpeg"
            },
            {
            "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/1458/product/slidedimmer.jpg?1423166301",
            "position": 2,
            "type": "image/jpeg"
            },
            {
            "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/1665/product/SlideDimmer.gif?1423166619",
            "position": 3,
            "type": "image/gif"
            },
            {
            "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2121/product/ProductImages_SlideDimmer.jpg?1423167844",
            "position": 4,
            "type": "image/jpeg"
            },
            {
            "url": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2176/product/Bit_Card_07_i5_SlideDimmer.jpg?1423168068",
            "position": 5,
            "type": "image/jpeg"
            }
        ]
    },
    "meta": {
        "version": 2,
        "criteria": {
            "method": "GET",
            "endpoint": "/api/v2/products/4/variants/4",
            "params": [
                {
                "name": "variant_id",
                "value": "4"
                },
                {
                "name": "product_id",
                "value": "4"
                }
            ]
        },
        "success": true,
        "errors": null
    }
}

Return

This returns a product with all of it’s variants and their associated images.

Projects

Get all published projects

curl "http://{server}/api/v2/projects?per_page=1"

The above command returns JSON structured like this:

{
  "results": [
      {
        "id": 16,
        "name": "littlePiggy Bank",
        "slug": "littlepiggy-bank--3",
        "icon": "https://lb-community-staging.s3.amazonaws.com/uploads/image/asset/776/small_pig3_interaction2_highRes.jpg",
        "description": "Interactive piggy bank that RINGS frantically to thank you for feeding it, BUZZES and LIGHTS up when you pet it’s ear, and SITS quietly when you want it to!<br>",
        "comment_count": 0,
        "like_count": 1,
        "liked_by_user": true,
        "user": {
          "id": 1750,
          "image": "https://lb-community-staging.s3.amazonaws.com/uploads/user/avatar/17/small_icon-green-ohhh.png",
          "slug": "littlebits",
          "username": "littleBits"
        }
      }
    ],
    "meta": {
      "criteria": {
        "method": "GET",
        "endpoint": "/api/v1/projects",
        "params": [
          {
            "name": "page",
            "value": 1
          },
          {
            "name": "per_page",
            "value": "1"
          }
        ]
      },
      "success": true,
      "errors": null
    }
}

GET http://{server}/api/v2/projects/

This request can be optionally authenticated to receive liked_by_user.

Query Parameters

Parameter	Type	Description
page	integer	Page number of returned results. Default is 1
per_page	integer	Number of results per page. Default is 10

Search projects

curl "http://{server}/api/v2/projects/search?kit=base-kit&per_page=1"

The above command returns JSON structured like previously.

GET http://{server}/api/v2/projects/search

This request can be optionally authenticated to receive liked_by_user.

Query Parameters

Parameter	Type	Description
q	string	Search projects by keyword
sort	string	Sort projects by most recent or popular. Accepts either `recent` or `popular`
days_ago	integer	Return projects published some number of days ago
tags	string	Return projects with a given tag
type	string	Defaults to projects only. Use `lesson` for lessons only.
kit	string	Return projects that can be built with this kit. Use slug of a kit.
variants	integer	Return projects with these variant IDs and not any others. Should be a comma separated list.
qty	integer	Return projects with this quantity of a corresponding variant ID. Must be a comma separated list of the same size as the list of variants.
user	integer	Return projects of a given user ID
page	integer	Page number of returned results. Default is 1
per_page	integer	Number of results per page. Default is 10

Get a project

curl "http://{server}/api/v2/projects/2055"

The above command returns JSON structured like this:

{
  "results":
  {
    "id": 2055,
    "name": "Sounding Box #11",
    "description": "Sounding Box #11 is the first piece to go public in a series of acoustic sculptures that allow viewers...",
    "comment_count": 1,
    "like_count": 10,
    "liked_by_user": false,
    "user": {
      "id": 47312,
      "image": "https://lb-community-staging.s3.amazonaws.com/uploads/user/avatar/small_Caselden_Studios_high_res.png",
      "slug": "caselden_studios",
      "username": "Caselden_Studios"
    },
    "credits": "God",
    "images": [
      {
        "id": 15,
        "url": "https://lb-community-staging.s3.amazonaws.com/uploads/image/asset/7755/large_filled_IMG_6771.jpg"
      }
    ],
    "embeds": [
      {
        "id": 5,
        "service": "youtube.com",
        "code": "<iframe width=\"560\" height=\"315\" src=\"//www.youtube.com/embed/IYJSEPD9T40\" frameborder=\"0\" allowfullscreen></iframe>"
      }
    ],
    "files": [],
    "tools": [
      {
        "id": 1,
        "name": "3D Printers"
      }
    ],
    "products": [
      {
        "product_id": 139,
        "variant_id": 133,
        "image": "https://s3.amazonaws.com/lb-spree-staging/spree/products/2046/small/arduino_withlogo.jpg?1423167635",
        "name": "Arduino",
        "quantity": 2
      }
    ],
    "materials": [
      {
        "id": 4,
        "name": "Assorted Paints and Finishing Oils",
        "quantity": 1
      }
    ],
    "steps": [
      {
        "id": 2,
        "number": 1,
        "title": "i am a jolly step title",
        "description": "<b>Make a sound box:</b><br>Design a resonating wooden chamber. We took design influence from...",
        "images": [
          {
            "id": 9896,
            "url": "https://lb-community-staging.s3.amazonaws.com/uploads/image/asset/9896/large_filled_PurpleBit.jpg",
            "caption": "Picture 1"
          }
        ]
      }
    ]
  },
  "meta": {
    "criteria": {
        "method": "GET",
        "endpoint": "/api/v1/projects/2055",
        "params": [
          {
            "name": "id",
            "value": 2055
          },
          {
            "name": "slug",
            "value": null
          }
        ]
      },
      "success": true,
      "errors": null
    }
  }

GET http://{server}/api/v2/projects/{:id|:slug}

This request can be optionally authenticated to receive liked_by_user.

Examples

GET http://{server}/api/v2/projects/16

GET http://{server}/api/v2/projects/robot

Projects Comments

GET comments

curl "http://{server}/api/v2/projects/774/comments"

The above command returns JSON structured like this:

{
  "results": [
    {
      "id":2996,
      "owner_id":15157,
      "body":"AWESOME!!!!  :)",
      "created_at":"2015-04-06T12:48:36.000Z",
      "replies":[]
    }
  ],
  "meta":{
    "version":2.0,
    "criteria":
    {
      "method":"GET",
      "endpoint":"/api/v2/comments/project/the-pune-rudefood",
      "params": [
        {
          "name":"page",
          "value":1
        },
        {
          "name":"per_page",
          "value":10
        },
        {
          "name":"id",
          "value":null
        },
        {
          "name":"slug",
          "value":"the-pune-rudefood"
        },
        {
          "name":"type",
          "value":"project"
        }
      ]
    },
    "success":true,
    "errors":null
  }
}

GET http://{server}/api/v2/projects/{:project_id}/comments

Examples

GET http://{server}/api/v2/projects/16/comments

Query Parameters

Parameter	Type	Description
page	integer	Page number of returned results. Default is 1
per_page	integer	Number of results per page. Default is 10

CREATE comment

curl -X POST -H "MobileAppAuth: {api_key}" -F "comment=first!" http://{server}/api/v2/projects/16/comments

The above command returns JSON structured like this:

{
  "results": [
    {
      "id":2996,
      "owner_id":15157,
      "body":"first!",
      "created_at":"2015-04-06T12:48:36.000Z",
      "replies":[]
    }
  ],
  "meta":{
    "version":2.0,
    "criteria":
    {
      "method":"GET",
      "endpoint":"/api/v2/comments/project/the-pune-rudefood",
      "params": [
        {
          "name":"id",
          "value":16
        },
        {
          "name":"type",
          "value":"project"
        },
        {
          "name":"body",
          "value":"first!"
        }
      ]
    },
    "success":true,
    "errors":null
  }
}

POST http://{server}/api/v2/projects/{:project_id}/comments

Reply

POST http://{server}/api/v2/projects/{:project_id}/comments/{:comment_id}

This request requires authentication.

Parameter	Type	Description
comment	string	Body of the comment.

Projects Likes

(un)Like a Project

curl -X POST -H "MobileAppAuth: {api_key}" http://{server}/api/v2/projects/16/like

The above command returns JSON structured like this:

{
  "results": {
    "like_count": 6,
    "liked_by_user": true
  },
  "meta":{
    "version":2.0,
    "criteria":
    {
      "method":"GET",
      "endpoint":"/api/v2/comments/project/16/like",
      "params": [
        {
          "name":"id",
          "value":16
        },
        {
          "name":"type",
          "value":"project"
        }
      ]
    },
    "success":true,
    "errors":null
  }
}

POST http://{server}/api/v2/projects/{:project_id}/like

This request requires authentication.

Users

Get a user

curl "http://{server}/api/v2/users/7"

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": 7,
      "username": "erin_littleBits",
      "twitter": "",
      "location": "boston, ma",
      "bio": "All the things!",
      "image": "https://lb-community-staging.s3.amazonaws.com/uploads/user/avatar/484/medium_DSC_4144_-_Version_2.JPG",
      "member_since": "Member since February 2015",
      "projects": [
        {
          "id": 176,
          "name": "Rudolph the Red-Nosed Reindeer",
          "slug": "rudolph-the-red-nosed-reindeer",
          "icon": "https://lb-community-staging.s3.amazonaws.com/uploads/lab/PurpleBit.jpg",
          "description": "Power + Pulse + RBG led = a littleBits powered blinking Rudolph nose!",
          "like_count": 1,
          "comment_count": 0,
          "user": {
            "id": 7,
            "image": "https://lb-community-staging.s3.amazonaws.com/uploads/user/avatar/484/small_DSC_4144_-_Version_2.JPG",
            "slug": "erin_littlebits",
            "username": "erin_littleBits"
          }
        },
      ]
    }
  ],
  "meta": {
    "version": 2,
    "criteria": {
      "method": "GET",
      "endpoint": "/api/v2/users/7",
      "params": [
        {
        "name": "id",
        "value": 7
        },
        {
        "name": "slug",
        "value": null
        }
      ]
    },
    "success": true,
    "errors": null
  }
}

GET http://{server}/api/v2/users/{:id|:slug}

Examples

GET http://{server}/api/v2/users/25038

GET http://{server}/api/v2/users/lev

Get a user’s Likes

curl "http://{server}/api/v2/users/sch/likes"

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": 1345,
      "name": "Real-Time Weather Dashboard",
      "slug": "real-time-weather-dashboard",
      "icon": "https://lb-community.s3.amazonaws.com/uploads/image/asset/4742/large_filled_weatherdashboard.jpg",
      "description": "<div>\r\n\t\t\t\t<div>\r\n\t\t\t\t\t<div>\r\n\t\t\t\t\t\t<p><b>Monitor current and forecasted weather data with littleBits and a little coding.</b> These customizable\r\nand modular weather boxes display current temperature, the forecasted high and low temperatures for the\r\nday, and the forecasted conditions for the day (i.e. sunny, cloudy, precipitation).\r\n</p>\r\n\t\t\t\t\t\t<p>Note: To complete this project, you will need to know how to work with APIs. The cloudBit’s API\r\ndocumentation can be found <a rel=\"nofollow\" target=\"_blank\" href=\"http://developer.littlebitscloud.cc/api-http\">here</a>. The Weather Underground's API documentation can be found <a rel=\"nofollow\" target=\"_blank\" href=\"http://www.wunderground.com/weather/api/d/docs?d=index\">here</a>.\r\n</p>\r\n\t\t\t\t\t\t<p><b>How they work:</b>\r\n</p>\r\n\t\t\t\t\t\t<p>We wrote a short program that gets information from Weather Underground and sends that data through the\r\nlittleBits cloud to a cloudBit. Every 30 minutes the program asks Weather Underground for the current\r\ntemperature and the forecasted high, low, and conditions for New York, NY. Then it converts this information\r\ninto a voltage* which is sent to each cloudBit, adjusting the angle of the servos (the servos must be set to\r\nturn mode for this to work). We've posted the code for our program here.\r\n</p>\r\n\t\t\t\t\t\t<p>*The program does not specify the volts, rather it sends a value from 0 to 100 which tells the cloudBit what\r\npercentage of the total power (5v) to output.&nbsp;</p>\r\n\t\t\t\t\t</div>\r\n\t\t\t\t</div>\r\n\t\t\t</div>",
      "comment_count": 8,
      "like_count": 23,
      "liked_by_user": null,
      "user": {
        "id": 1750,
        "image": "https://lb-community.s3.amazonaws.com/uploads/user/avatar/17/small_avatars_output-03.png",
        "slug": "littlebits",
        "username": "littleBits"
      }
    }
  ],
  "meta": {
    "version": 2,
    "criteria": {
      "method": "GET",
      "endpoint": "/api/v2/users/sch/likes",
      "params": [
        {
          "name": "id",
          "value": null
        },
        {
          "name": "slug",
          "value": "sch"
        }
      ]
    },
    "success": true,
    "errors": null
  }
}

GET http://{server}/api/v2/users/{:id|:slug}/likes

Examples

GET http://{server}/api/v2/users/25038/likes

GET http://{server}/api/v2/users/lev/likes

Create a user

POST http://{server}/api/v2/users/new

Form Data

Parameter	Description
user[email]	New user’s email address
user[username]	New user’s username
user[password]	New user’s password
user[password_confirmation]	New user’s password

Password Reset

GET http://{server}/api/v2/users/password_reset?email=e@ma.il

Status Codes

The littleBits API uses the following status codes:

Status Code	Meaning
200	OK
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Unprocessable Entity
500	Internal Server Error

Introduction

API Responses

LB API Response Format

Documentation Format

Authentication

Login

Testing on Staging Servers

HTTP Request

Form Data

Login with Facebook

Log out

HTTP Request

Form Data

Content

GET Content

List

HTML

Getting CMS Content

Responses

Current Keys

My Library

GET all modules

HTTP Request

CREATE new module

HTTP Request

UPDATE existing module

HTTP Request

DELETE module

HTTP Request

Product and Variants

GET All Products

Example

Return

GET Product

Example

Return

GET Variant

Example

Return

Projects

Get all published projects

Query Parameters

Search projects

Query Parameters

Get a project

Examples

Projects Comments

GET comments

Examples

Query Parameters

CREATE comment

Reply

Projects Likes

(un)Like a Project

Users

Get a user

Examples

Get a user’s Likes

Examples

Create a user

Form Data

Password Reset

Status Codes