Authentication

Every call to the Rebrickable API needs to be authenticated in one of two ways (these examples use a fake key b4e0697ce3d5cf21af1088e9bd238dd):

  1. Authorization Header - add a HTTP header named Authorization with the value of key b4e0697ce3d5cf21af1088e9bd238dd (Note that your key must be prefixed with the text 'key ').
    curl --header 'Authorization: key b4e0697ce3d5cf21af1088e9bd238dd' https://rebrickable.com/api/v3/lego/colors/
  2. GET/POST parameter - include a GET or POST parameter called key with your key value.
    curl https://rebrickable.com/api/v3/lego/colors/?key=b4e0697ce3d5cf21af1088e9bd238dd

Standard Parameters

For the GET calls that return a list of items, there are some optional parameters to help process the list results.

  1. page - Lists are automatically paginated, and currently use a page size of 1000 (might change in the future). By default, it will only return results for the first page of items. You can request additional pages with the 'page' parameter (base 1). Alternatively, there is always a 'next' and 'previous' field in the results which contains the URL for the next and previous page of results.
  2. page_size - The number of results to display for returned lists. Defaults to 100, but can be increased to a maximum of 1000 if required.
  3. ordering - supported calls can be ordered by using the 'ordering' parameter. Simply provide the name of one of the top-level result fields to order by, or a comma separated (encoded to %2C) list of fields for nested ordering. If you place a - in front of a field name it will be sorted in reverse order.

Example:

curl https://rebrickable.com/api/v3/lego/colors/?key=b4e0697ce3d5cf21af1088e9bd238dd&page=2&ordering=-name%2Cid

REST Methods

This v3 API is based on a REST framework. This means the HTTP method types you use determines what happens with the data. Some REST definitions have differing behavious, so to make things clear this is what the Rebrickable API uses:

  • GET - Used to RETRIEVE items, always a read only operation.
  • POST - Used to CREATE new items. If the item already exists, it will fail. Sometimes also used in place of GET calls if there are too many parameters or the data is too sensitive to be placed in a URL.
  • PUT - Used to REPLACE existing items, you must specify every field. If the item does not exist it will fail.
  • PATCH - Used to partially UPDATE existing items if you only want to change some of the fields. If the item does not exist it will fail.
  • DELETE - Used to DELETE an existing item.

Response Codes

200Success
201Successfully created item
204Item deleted successfully
400Something was wrong with the format of your request
401Unauthorized - your API key is invalid
403Forbidden - you do not have access to operate on the requested item(s)
404Item not found
429Request was throttled - you are sending too many requests too fast. Normal user accounts are allowed to send on average one request/sec, with some small allowance for burst traffic. Example response:
{ "detail": "Request was throttled. Expected available in 2 seconds." }

Performance Tips

Calling the API for every part item can be slow and trigger throttle errors, or cause slow downs for everyone.

For example, instead of:

/lego/parts/3001/
/lego/parts/3002/
/lego/parts/3003/

It is far more efficient to perform a single call with:

/lego/parts/?part_nums=3001,3002,3003&inc_part_details=1

Change Log

While I try my best to keep this API stable, there are inevitable bug fixes and small enhancements added over time. Most of the time they should not break existing functionality.

DateChange
2019-05-10Add print_of field to part detail view /lego/parts/{part_num}/.
2018-05-25Part color details now uses correct color in the part_img_url field.
2018-04-11Inventory parts list now uses correct color in the part.part_img_url field.
2018-04-11External system filters in /lego/parts/ no longer return the external part number if an external system mapping is in place
2018-03-10Added inc_part_details option to endpoints: /lego/parts/, /lego/parts/{part_num}/, /sets/{set_num}/parts/, /users/{user_token}/parts/, /users/{user_token}/partlists/{list_id}/parts/, /users/{user_token}/allparts/ which will return all detailed part fields for each part in the list.
2018-03-10Added part_nums filter param to /lego/parts/
2018-03-10Reduce default page_size to 100
2017-09-26Include disabled Elements in responses
2017-09-14Added external_ids section to Part listings
2017-05-23/users/{token}/profile/ now returns additional fields: username, email, avatar_img
2017-05-23/lego/sets/ search field now looks at both name and set_num
2017-04-21Add proper headers in CORS responses
2017-04-19Allow unauthenticated OPTIONS requests to help Ember apps (although it will not check if any authentication header is valid for the following GET/etc call)
2017-04-13Include CORS header on 40x responses to help Angular apps
2017-03-29Added element_img_url and part_img_url to /lego/elements/{element_id}/
2017-03-07Added optional page_size query parameter for list results (default is still 1000 but will be reduced soon)
2017-02-09Added calls for /users/{user_token}/sets/{set_num}/
2017-02-09Added designer_name and designer_url to MOC response model

Help!

If you need assistance or think you've found a bug, please post to the API Forum.

Swagger Documentation

Swagger URL = https://rebrickable.com/api/v3/swagger/?format=openapi