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 Apply for an API Key to call these services.

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 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.
    • 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 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.
    • 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 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. 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

    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.

    URL /api/get_part
    Method GET
    Parameters key - API Key
    part_id - The Part ID to look up (e.g. 3001)
    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:
    Format:
    e.g.: xml, json

    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