Rebrickable API

We have several web services for directly accessing the various Rebrickable functions and data from your own applications or web sites. To be able to use these, you must first Generate an API Key from your profile's settings page (if you don't already have an account sign up here).

These functions act on a specified user account:
  • Get User Hash - Get a user's hash key to allow calling subsequent functions without email/password.
  • Get User Last Change - Get the date/time of the last change to the user's inventory (sets or loose parts).
  • Get Set Match % - Find out how many parts are missing from a set.
  • Set User Sets - Set the user's entire set list.
  • Get User Sets - Get the user's entire set list.
  • Get User Set Lists - Get the user's set lists.
  • Set User Set - Set the quantity for a single set (or add or delete the set).
  • Get User Set - Find out how many of a single set the user has.
  • Set User Parts - Set the user's entire loose parts list.
  • Get User Parts - Get the user's entire loose parts list.
  • Set User Lost Parts - Set the user's entire lost parts list.
  • Get User Lost Parts - Get the user's entire lost parts list.
  • These are general set inventory functions:
  • Get Set Parts - Get a list of all parts (normal + spare) used in a set.
  • Get Part - Get details about a specific part.
  • Get Element - Get details about a specific LEGO element ID (ie part design and color).
  • Get Set - Get details about a specific set.
  • Get Part Sets - Get the list of sets that a specific part/color appears in.
  • Get Colors - Get the list of colors used by all parts.
  • Get Changes - Get the list of set/part changes since some point in time.
  • Get Alternate Build MOCs - Get a list of MOCs that are alternate builds of the specific set.
  • 2014-10-20 - get_element - Created function.
    2014-10-18 - get_alt_builds - Added num_parts field.
    2014-10-16 - get_alt_builds - Added CSV format.
    2014-10-16 - get_user_sets - Fixed output formatting when no format parameter supplied.
    2014-09-30 - get_alt_builds - Added image fields to result.
    2014-09-12 - get_alt_builds - Created function.
    2014-09-07 - get_changes - Created function.
    2014-08-01 - get_part - Now returns rebrickable_part_id when available even if the requested part doesn't exist (e.g. LDD part 74741 -> Rebrickable part 2909c03).
    2014-07-07 - get_part - Added additional return field: rebrickable_part_id.
    2014-06-01 - get_colors - Fixed XML output.
    2014-05-03 - get_part - Added additional return field: category.
    2014-05-03 - get_set - Created function.
    2014-05-03 - get_user_last_change - Created function.
    2014-03-05 - get_set_parts - Added additional return fields: element_id, element_img_url.
    2014-01-25 - get_part - Added optional parameters inc_rels and inc_ext to return additional part relationships and external part id information.
    2013-11-25 - get_user_sets - Added additional return fields: #pieces, description, year, thumbnail image url.
    2013-11-23 - set_user_lost_parts - Created function.
    2013-11-23 - get_user_lost_parts - Created function.
    2013-09-16 - get_set_parts - Fixed problem with part_img_url field for spare parts.
    2013-05-06 - get_user_sets - Added optional setlist_id parameter.
    2013-05-04 - set_user_sets - Added optional setlist_id parameter.
    2013-05-04 - set_user_setlists - Created function.
    2013-04-07 - set_user_parts/get_user_parts - Created new functions.
    2013-04-03 - get_user_hash - Created function and updated all other user functions to accept the user_hash parameter as an alternative to email/pass.
    2013-04-01 - get_set_parts - Added additional return fields: set_img_url, part_name, color_name, part_img_url.
    2013-04-01 - get_part - Created function.
    2013-04-01 - get_part_sets - Created function.
    2013-04-01 - get_colors - Created function.

    Get User Hash

    Use this service to get a user's hash key. This is a 32-character key which can be used instead of an email/password combination when calling any of the below API functions. It is designed to prevent having to store passwords in external applications. The user's hash key is valid until the user changes their email address or password.

    URL/api/get_user_hash
    MethodGET
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    Returns INVALIDKEY - The API Key is invalid
    INVALIDUSERPASS - Invalid user email or password
    <data> - 32 character hash key uniquely identifying and authenticating the user.

    Test Values

    API Key:
    User email:
    User password:

    Test Results

    Get User Last Change

    Get the date/time of the last change to the user's collection, either sets or loose parts.

    URL/api/get_user_last_change
    MethodGET
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    Returns NOUSER - The user does not exist
    INVALIDKEY - The API Key is invalid
    INVALIDUSERPASS - Invalid user email or password
    INVALIDHASH - The hash key does not match a user/password
    <data> - Timestamp (YYYY-MM-DD HH24:MI:SS) in UTC.

    Test Values

    API Key:
    User email:
    User password:
    User Hash:

    Test Results

    Get Set Match %

    Use this service to find out how many parts the user needs to build the specified set. This will use any sets and loose parts the user has configured in their account. It returns two numbers - the total number of parts in the set and the number of parts the user is missing - so you can calculate the % yourself.

    URL/api/get_set_match
    MethodGET
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    set - The set id to check (e.g. 8258-1)
    format - How to display output data. Valid values: xml, json, csv, tsv
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    NOSET - The set could not be found
    <data> - Success, shows both total number of parts and the number missing. The third value shows the date/time of the last modification to the user's set list in the format YYYY-MM-DD HH24:MI:SS (in UTC time). You can use this to determine if the sets are up to date or not.

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Set ID:
    e.g.: 8258-1
    Format:
    e.g.: xml, json, csv, tsv

    Test Results

    Set User Sets

    Use this service to set the Rebrickable sets saved in the specified user's My Sets list. It will merge these sets with any existing sets. However if you specify the optional setlist_id parameter, it will instead replace (ie not merge) all sets just in that specific set list. If any sets cannot be found in the database, they will be silently ignored. For this reason, when it has finished it will return the number of sets that were successfully recognised.

    URL /api/set_user_sets
    MethodPOST
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    sets - The list of sets to be added: SET QTY, SET QTY, etc
    setlist_id - The ID of the user's set list to add to (optional)
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    SUCCESS [int sets added] - Successfully added the indicated number of sets

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Sets:
    e.g.: 8258-1 1, 8043-1 2
    Set List ID:

    Test Results

    Get User Sets

    Use this service to get all the sets saved in the specified user's Set Lists.

    URL /api/get_user_sets
    Method GET
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    format - How to display output data. Valid values: xml, json, csv
    setlist_id - The ID of the user's set list to retrieve (leave out to combine all setlists)
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    <data> = list of sets and quantities

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Format:
    e.g.: xml, json, csv, tsv
    Set List ID:

    Test Results

    Get User Set Lists

    Use this service to get the user's Set Lists. This can be used with get_user_sets to get the full list of sets for each setlist.

    URL /api/get_user_setlists
    Method GET
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    format - How to display output data. Valid values: xml, json, csv
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    <data> = list of setlists and their details

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Format:
    e.g.: xml, json, csv, tsv

    Test Results

    Set User Set

    Use this service to set the quantity of a single set saved in the specified user's My Sets list. Use 0 to delete the set. If the user does not have the set, it will add the specific number of them.

    URL /api/set_user_set
    MethodPOST
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    set - The Set ID to be updated
    qty - The new quantity (0 to delete it)
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    NOSET - The set could not be found (e.g. invalid)
    SUCCESS - Successfully updated the set quantity

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Set ID:e.g.: 8258-1
    Qty:

    Test Results

    Get User Set

    Use this service to get a single set saved in the specified user's My Sets list. If they don't have the set, it will return a quantity of 0.

    URL /api/get_user_set
    Method GET
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    set - The Set ID to look up (e.g. 8258-1)
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    NOSET - The set could not be found (e.g. invalid)
    <int> = how many of this set the user has, 0 if none.

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Set ID:

    Test Results

    Set User Parts

    Use this service to set the list of loose parts saved in the specified user's My Parts list. It will first delete any existing parts, so you should always pass in the complete list. If any parts cannot be found in the database, they will be silently ignored. The usual translation of part IDs will occur as per any parts import process (e.g. Bricklink part numbers converted to LDraw where they are different). It will return the number of parts that were successfully recognised.

    URL /api/set_user_parts
    MethodPOST
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    parts - The list of parts to be added: PART COLOR QTY, PART COLOR QTY, etc
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    SUCCESS [int parts added] - Successfully added the indicated number of parts

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Parts:
    e.g.: 3001 71 10, 3001 4 2

    Test Results

    Get User Parts

    Use this service to get a user's list of loose parts as shown on their My Parts page.

    URL /api/get_user_parts
    Method GET
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    format - How to display output data. Valid values: xml, json, csv
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    <data> = The list of parts, colors and quantities.

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Format:
    e.g.: xml, json, csv, tsv

    Test Results

    Set User Lost Parts

    Use this service to set the list of lost parts shown in user's My Lost Parts list. It will first delete any existing parts, so you should always pass in the complete list. If any parts cannot be found in the database, they will be silently ignored. It will return the number of parts that were successfully recognised.

    URL /api/set_user_lost_parts
    Method POST
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    parts - The list of parts to be added: PART SET COLOR QTY, PART SET COLOR QTY, etc
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    SUCCESS [int parts added] - Successfully added the indicated number of parts

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Parts:
    e.g.: 4865a 75018-1 0 1, 3666 9607-1 71 1

    Test Results

    Get User Lost Parts

    Use this service to get a user's list of lost parts as shown on their My Lost Parts page.

    URL /api/get_user_lost_parts
    Method GET
    Parameters key - API Key
    email - Registered user's email address
    pass - Registered user's password
    hash - User Hash Key, alternate to providing email+pass
    format - How to display output data. Valid values: xml, json, csv
    Returns INVALIDKEY - The API Key is invalid
    NOUSER - The user does not exist
    INVALIDPASS - The password does not match the user
    INVALIDHASH - The hash key does not match a user/password
    <data> = The list of parts, sets, colors and quantities.

    Test Values

    API Key:
    User email:
    User password:
    User Hash:
    Format:
    e.g.: xml, json, csv, tsv

    Test Results

    Get Set Parts

    Use this service to get a list of all parts in a set. It includes both normal and spare parts.

    URL /api/get_set_parts
    Method GET
    Parameters key - API Key
    set - The Set ID to look up (e.g. 8258-1)
    format - How to display output data. Valid values: xml, json, csv, tsv
    Returns INVALIDKEY - The API Key is invalid
    NOSET - The set could not be found (e.g. invalid)
    <data> Output data.

    Test Values

    API Key:
    Set ID:
    Format:
    e.g.: xml, json, csv, tsv

    Test Results

    Get Part

    Use this service to get details about a part, such as its name, number of sets it appears in, which colors it appears in, etc. Relationships provide a list of printed parts, different molds etc. External IDs provide a list of the part ids for other systems where they are different to Rebrickable, such as Bricklink, Peeron, LDraw or LEGO element IDs. If the field rebrickable_part_id exists, that means this part is not used in any Rebrickable inventories and you should use the specified part instead.

    URL /api/get_part
    Method GET
    Parameters key - API Key
    part_id - The Part ID to look up (e.g. 3001)
    inc_rels - Optional flag (1 or 0) to include Part Relationships in return data (may be a lot of data for some parts)
    inc_ext - Optional flag (1 or 0) to include external Part IDs (may be a lot of data for some parts due to LEGO element ids)
    format - How to display output data. Valid values: xml, json
    Returns INVALIDKEY - The API Key is invalid
    NOPART - The part could not be found (e.g. invalid)
    <data> Output data.

    Test Values

    API Key:
    Part ID:
    Include Relationships?:
    Include External IDs?:
    Format:
    e.g.: xml, json

    Test Results

    Get Element

    Use this service to get a part's design id and color based on a LEGO element id.

    URL /api/get_element
    Method GET
    Parameters key - API Key
    element_id - The Element ID to look up
    format - How to display output data. Valid values: xml, json, csv
    Returns INVALIDKEY - The API Key is invalid
    NOPART - The part could not be found (e.g. invalid)
    <data> Output data.

    Test Values

    API Key:
    Element ID:
    Format:
    e.g.: xml, json, csv

    Test Results

    Get Set

    Use this service to get details about a set, such as .

    URL /api/get_set
    Method GET
    Parameters key - API Key
    set_id - The Set ID to look up (e.g. 8043-1)
    format - How to display output data. Valid values: xml, json, csv, tsv
    Returns INVALIDKEY - The API Key is invalid
    NOSET - The set could not be found (e.g. invalid)
    <data> Output data.

    Test Values

    API Key:
    Set ID:
    Format:
    e.g.: xml, json, csv, tsv

    Test Results

    Get Part Sets

    Use this service to get a list of all sets that a specific part/color combination appears in. This is best used after calling the get_part function to retrieve the list of available colors.

    URL /api/get_part_sets
    Method GET
    Parameters key - API Key
    part_id - The Part ID to look up (e.g. 3001)
    color_id - The LDRAW based Color ID to look up (e.g. 0 = black)
    format - How to display output data. Valid values: xml, json
    Returns INVALIDKEY - The API Key is invalid
    NOPART - The part/color could not be found or has no sets
    <data> Output data.

    Test Values

    API Key:
    Part ID:
    Color ID:
    Format:
    e.g.: xml, json

    Test Results

    Get Colors

    Use this service to get a list of all the colors used by parts in the database. Basically the data in this table.

    URL /api/get_colors
    Method GET
    Parameters key - API Key
    format - How to display output data. Valid values: xml, json, csv, txt
    Returns INVALIDKEY - The API Key is invalid
    <data> Output data.

    Test Values

    API Key:
    Format:
    e.g.: xml, json, csv, txt

    Test Results

    Get Changes

    Get a list of all changes (sets, mocs, parts, inventories) since a point in time. Use this to apply delta changes within your app/site instead of downloading the entire catalog. Max entries returned is 1000.

    URL /api/get_changes
    Method GET
    Parameters key - API Key
    timestamp - Timestamp as epoch UTC time zone
    format - How to display output data. Valid values: xml, json, csv, txt
    Returns INVALIDKEY - The API Key is invalid
    <data> Output data.

    Test Values

    API Key:
    Timestamp (epoch UTC):
    Format:
    e.g.: xml, json

    Test Results

    Get Alternate Build MOCs

    Get a list of any alternate build MOCs based on a specific set. These MOCs use only the parts from a single set.

    URL /api/get_alt_builds
    Method GET
    Parameters key - API Key
    format - How to display output data. Valid values: xml, json, csv
    set_id - The Set ID to look for MOCs of.
    Returns INVALIDKEY - The API Key is invalid
    <data> Output data.

    Test Values

    API Key:
    Set ID:
    Format:
    e.g.: xml, json, csv

    Test Results