Clicky

Loading

Getting Started

The Thingiverse API was written to follow the design patterns laid out by GitHub and Facebook. We try to adhere to the following general principles:

  • All API access is over HTTPS and access via the api.thingiverse.com domain
  • All data is sent and received as JSON
  • Errors are sent using standard HTTP response codes (400, 404, 403)
  • Actions are indicated by HTTP verbs: GET, POST, PATCH, DELETE
  • All authentication is done via OAuth2 bearer tokens
  • Pagination uses ?page and ?per_page parameters
  • Pagination URLs are included as Link headers
  • CORS headers are issued for the origin specified by the app
  • JSON-P callbacks are available using the ?callback parameter

Where we differ from GitHub:

  • All API requests require authentication for now
  • Unapproved applications only allow up to 10 users for now
  • Rate limiting is 300 per 5 minute window instead of 5000 per hour
  • Basic authentication is not available
  • OAuth tokens must be sent via the Authorization header with the prefix “Bearer”
  • Non-web application flow is not yet supported, users will need to be directed through a browser
In general many of the basic mechanisms laid out in the GitHub API v3 documentation overview can be followed here although the specific names of parameters may differ.

Registering an application

You can register your app by visiting https://www.thingiverse.com/apps/create. At a minimum you will need to supply the following:

  • The name of your app
  • A brief description what your app does
  • The type of app you’re building (see below)
  • A URL where users can find out more information
  • The URL where your app lives (if it’s web-based)
  • A callback URL for the authentication mechanism

Application Types

There are four kinds of applications that can be built with the Thingiverse API:
  • Web - An application that operates in a web browser, but outside the Thingiverse site.
  • Thing - An application that operates within the Thingiverse site by loading inside of an iframe. These apps can use the Thingiverse Javascript API to present dialogs to the user for common functions.
  • Mobile (iOS or Android) - A standalone application that will operate in a mobile or tablet environment.
  • Desktop - A standalone application that will operate on a desktop computer environment.

Web and Thing apps will need to specify the URL where the app lives and should include a callback URL.

Your app will be private until you publish it and the Thingiverse moderators review and approve it. While your application is private you can have up to 10 people register and play with it.

General App Guidelines

Below is a list of general App guidelines that all Thingiverse Apps should follow. All Apps will be reviewed before being approved for publish according to these guidelines.

  • Thingiverse Apps should contribute value to Thingiverse users and help the 3D printing community in a positive way.
  • Apps need to have some kind of benefit and value to Thingiverse users and are not allowed to use data or files from Thingiverse without contributing any value to Thingiverse users.
  • If an app has an object or file that it produces, the app should always set the default action to easily lets users post back to Thingiverse in order to contribute back to the community instead of redirecting elsewhere. When doing so the following guidelines should be followed:
    • If the user is the owner of the Thing they are editing, the option to post resulting files back to the Thing should be presented to them.
    • If the user is not the owner of the Thing but the Thing allows derivatives, the option to post a Remix back to Thingiverse should be presented. When doing this, the ancestor field of the new Thing should be set accordingly so that the new Thing appears as a remix of the original.
    • If the user is not the owner of the Thing and the Thing does NOT allow derivatives, the option to download the file should be presented to the user instead of posting to Thingiverse as a remix.
  • Payment processing must be processed through the Thingiverse payments system.
  • Shipping addresses must be collected via the Thingiverse address system.
  • Apps must not sell or otherwise commercialize Thingiverse user's' content without permission from both parties.
  • Apps must not use Things or user data in a malicious or disruptive way.
  • Apps must not redistribute Thingiverse content on other sites or platforms.
  • Apps must recognize and properly handle usability based on Thing licenses.
  • Apps must not create spam or other advertising material using the API.
  • Finally, Thingiverse Apps must always abide by the Thingiverse API Terms of Service.

Authentication

Thingiverse uses the OAuth2 web application flow for authentication and authorization. Developers will need to register their application before getting started. Each application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared or sent to the browser.

Note that all the URLs used in the authentication section are using the www.thingiverse.com domain and not api.thingiverse.com. Only use the api.thingiverse.com endpoint once you have a valid access token.

Step 1. Direct users to request Thingiverse access

Open a browser (or redirect) to the url specified below. The user will be prompted to authorize your app for access to their Thingiverse account.

          GET https://www.thingiverse.com/login/oauth/authorize
Parameters
  • client_id - Required string - The client ID you received from Thingiverse when you registered.
  • redirect_uri - Optional string - URL in your app where users will be sent after authorization.
  • response_type - Optional string - Use "token" to authorize client-side applications. We follow a similar procedure as Google's Using OAuth 2.0 for Client-side Applications. If none specified, default is code.

Step 2. Thingiverse redirects back to your site

If the user accepts your request, Thingiverse redirects back to your site with:

  • If response_type=code is set in Step 1, a temporary code in a code parameter.
  • If response_type=token is set in Step 1, a fragment with an access_token parameter

          GET http://www.yourgreatapp.com/callback?code=195a675aba3473f3d11b8f851009a958

Or, using response_type=token

          GET http://www.yourgreatapp.com/callback#access_token=e72e16c7e42f292c6912e7710c838347ae178b4a

Step 3. Exchange code for an access token or validate the token (for response_type=token)

A. Exchange code

Send the code along with your client id and client secret to get an access token that can be used to interact with Thingiverse on the user’s behalf. If your application is web-based make sure you’re doing this from the backend to prevent sharing your secret with the client.

          POST https://www.thingiverse.com/login/oauth/access_token
Parameters
  • client_id - Required string - The client ID you received from Thingiverse when you registered.
  • redirect_uri - Optional string
  • client_secret - Required string - The client secret you received from Thingiverse when you registered.
  • code - Required string - The code you received as a response to Step 2.
Response

The response will be in URL encoded form.

          access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer

B. Validate token

Send the access token received in Step 2.

When verifying a token, it is critical to ensure the audience field in the response exactly matches the client ID of your app to avoid a confused deputy situation. 
          POST https://www.thingiverse.com/login/oauth/tokeninfo
Parameters
  • access_token - Required string - The access token you received from Step 2 using response_type=token.
Response

The response will be a JSON array that describes the token or an error.

            {
              "audience":YOUR_CLIENT_ID,
              "user_id":"244"
            }

Step 4. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user. You can either use the token in the Authorization: Bearer HTTP header or include it as the access_token query parameter. The first call your app will probably want to make is to /users/me to find out some basic information about the user who is using your app.

Request

Using the Authorization: Bearer HTTP header: 

          GET https://api.thingiverse.com/users/me
          Authorization: Bearer e72e16c7e42f292c6912e7710c838347ae178b4a

Or Using the access_token query parameter: 

          GET https://api.thingiverse.com/users/me?access_token=e72e16c7e42f292c6912e7710c838347ae178b4a
Response
        {
          "id":50577,
          "name":"thingiverse",
          "url":"https://api.thingiverse.com/users/thingiverse",
          "thumbnail":"https://cdn.thingiverse.com/renders/0a/51/60/8b/cc/Thingiverse-Avatar_v2-1_thumb_medium.jpg",
          "bio":"",
          "location":"Brooklyn, NY",
          "registered":"2013-02-22T21:32:27+00:00",
          "last_active":"2015-12-02T16:47:12+00:00",
          "things":"https://api.thingiverse.com/users/thingiverse/things",
          "copies":"https://api.thingiverse.com/users/thingiverse/copies",
          "likes":"https://api.thingiverse.com/users/thingiverse/likes",
          "default_license":"cc",
          "email":"thingiverse@makerbot.com"
        }

Webhooks

If desired, your app may specify a webhook URL, to which a POST request will be sent upon order-related events occuring on Thingiverse. At present, those events are when an order is created, when a refund for an order is requested, and when a refund is granted.

To specify a webhook for your app, enter the URL for the webhook on the Edit page for your app.

Click the "Test" button on the app edit page, underneath the textbox into which you may specify the webhook URL, in order to send a demonstration "ping" to your app. If successful, your app will receive a JSON object in the body of a request with the following format:

Test Webhook Request
        {
            "event": "ping"
        }

Webhook requests sent from Thingiverse to your webhook URL will contain JSON data, respective to the event which triggered the webhook. Expect one of the following JSON objects in the body of a webhook request:

New Order Created
            {
                "event": "order_created"
                "order": {
                    "id": "1234",
                    "thing_id": "1234",
                    "amount": "14.53",
                    "add_date": "2016-04-28 16:28:40",
                    "modified_date": "2016-04-29 08:03:38",
                    "charges": [array of charges],
                    "fees": "0.54",
                    "validated_shipping_address": "123 Some St., Somecity, Somestate, 12345",
                    "is_shipped": "true",
                    "status": "status",
                    "note": "a note"
                }
            }
Order Refund Requested
            {
                "event": "refund_requested"
                "order": {
                    "id": "1234",
                    "thing_id": "1234",
                    "amount": "14.53",
                    "add_date": "2016-04-28 16:28:40",
                    "modified_date": "2016-04-29 08:03:38",
                    "charges": [array of charges],
                    "fees": "0.54",
                    "validated_shipping_address": "123 Some St., Somecity, Somestate, 12345",
                    "is_shipped": "true",
                    "status": "status",
                    "note": "a note"
                }
            }
Order Refund Granted
            {
                "event": "order_refunded"
                "order": {
                    "id": "1234",
                    "thing_id": "1234",
                    "amount": "14.53",
                    "add_date": "2016-04-28 16:28:40",
                    "modified_date": "2016-04-29 08:03:38",
                    "charges": [array of charges],
                    "fees": "0.54",
                    "validated_shipping_address": "123 Some St., Somecity, Somestate, 12345",
                    "is_shipped": "true",
                    "status": "status",
                    "note": "a note"
                }
            }

What's Next

Once your app is able to authenticate and start making API calls you're ready to dive in. Check out these resources to help you on your way.