Dribbble API

All API access is over HTTP. All responses are returned as JSON. The API is (mostly) RESTful.

Currently, no API key is required, but this will likely change so we can better monitor usage and enforce the Terms of Use (below). The API has been stable, but will retain the beta moniker until API keys are added.

API calls are limited to 60 per minute and 10,000 per day. We may change the limit in the future and/or tie it to API keys. Exceeding the limit will result in 403 “Rate Limit Exceeded” responses.

Contact us with comments, questions or feedback on the API.

We’re short on lawyers, so our terms are brief. As our values and content are similar to those at Flickr, we recommend that you read their more extensive Flickr APIs Terms of Use to get a sense of how the Dribbble API may (and may not) be used. Regarding the branding and design of your application, please read our Brand Guidelines. With that said, here’s our rule book:

• Dribbble members own all rights to their content and it is your responsibility to make sure your use of the API does not contravene those rights.
• You must remove from your application within 24 hours any Dribbble shot or personal information that the owner asks you to remove.
• Don’t use the name Dribbble in your application, url or branding. Don’t use Dribbble artwork in your application except as allowed by the Brand Guidelines.
• Do not use the Dribbble API for any application that replicates or attempts to replace the essential user experience of dribbble.com
• If your application derives revenue from its use of the Dribbble API, directly or indirectly, it is considered a commercial application and requires our approval in advance.
• Dribbble reserves the right to evaluate and monitor applications to ensure that they do not harm Dribbble’s servers or business interests.
• Do not abuse the API or use it excessively. If you’re unsure whether your planned use is excessive, ask us.
• Dribbble may terminate your license to the Dribbble API under these terms at any time for any reason.
• Dribbble reserves the right to update and change these terms from time to time without notice.

The Dribbble API is available for non-commercial use. Commercial use is possible by prior arrangement. Please contact us if you wish to apply for commercial use of the API.

Where possible, the API strives to use appropriate HTTP verbs for each action.

There are two ways to authenticate through Dribbble API.

OAuth2 Token (sent in a header)

curl -H "Authorization: Bearer OAUTH_TOKEN" https://api.dribbble.com/v1/user

OAuth2 Token (sent as a parameter)

curl https://api.dribbble.com/v1/user?access_token=OAUTH_TOKEN

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the page parameter. For some resources, you can also set a custom page size up to 100 with the per_page parameter. Note that for technical reasons not all endpoints respect the per_page parameter.

$ curl https://api.dribbble.com/v1/user/followers?page=2&per_page=100

Note that omitting the page parameter will return the first page.

The pagination info is included in the Link header. It is possible for some resources in the future to not be paginated based on page number, so it is important to follow these Link header values instead of constructing your own URLs.

Link: ; rel="prev",
  ; rel="next"

The possible rel values are:

Most responses return an ETag header. Many responses also return a Last-Modified header. You can use the values of these headers to make subsequent requests to those resources using the If-None-Match and If-Modified-Since headers, respectively. If the resource has not changed, the server will return a 304 Not Modified.

$ curl -i https://api.dribbble.com/v1/users/simplebits
HTTP/1.1 200 OK
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2014 17:10:33 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

$ curl -i https://api.dribbble.com/v1/users/simplebits -H 'If-None-Match: "e612e16d3c4d113573edb015d8eac1d5"'
HTTP/1.1 304 Not Modified
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2014 17:10:33 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

$ curl -i https://api.dribbble.com/v1/users/simplebits -H "If-Modified-Since: Sat, 22 Feb 2014 17:10:33 GMT"
HTTP/1.1 304 Not Modified
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2014 17:10:33 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

You can make up to 60 requests per minute, with a hard limit of 10,000 per day. For requests using OAuth, the rate limit is for each application and user combination. For unauthenticated requests, the rate limit is for the requesting IP address.

You can check the returned HTTP headers of any API request to see your current per minute rate limit status:

$ curl -i https://api.dribbble.com/v1/users/simplebits

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

The headers tell you everything you need to know about your current rate limit status - see Common Headers section

If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.

new Date(1392321600 * 1000)
// => Thu Feb 13 2014 14:00:00 GMT-0600 (CST)

Once you go over the rate limit you will receive an error response:

HTTP/1.1 429 Too Many Requests
Status: 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1392321600

{ "message" : "API rate limit exceeded." }

Staying within the rate limit

If you are exceeding your rate limit, you can likely fix the issue by caching API responses. If you’re caching and still exceeding your rate limit, please contact us to request a higher rate limit for your OAuth application.

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests. You can read the CORS W3C working draft, or this intro from the HTML 5 Security Guide.

Here’s a sample request sent from a browser hitting http://example.com:

$ curl -i https://api.dribbble.com/v1/users/simplebits -H "Origin: http://example.com"
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Expose-Headers: ETag, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Allow-Credentials: true

This is what the CORS preflight request looks like:

$ curl -i https://api.dribbble.com/v1/users/simplebits -H "Origin: http://example.com" -X OPTIONS -H "Access-Control-Request-Method: GET"
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: OPTIONS, GET
Access-Control-Expose-Headers: ETag, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true

You can send a callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.

$ curl https://api.dribbble.com?callback=bar

bar({
  "meta" : {
    "status" : 200,
    "X-RateLimit-Limit" : 60,
    "X-RateLimit-Remaining" : 59,
    "X-RateLimit-Reset" : 1392321600,
    "Link" : [
      ["https://api.dribbble.com?page=2", { "rel" : "next" }]
    ]
  },
  "data" : {
    // ...
  }
})

You can write a JavaScript handler to process the callback like this:

function bar(response) {
  var meta = response.meta
  var data = response.data

  console.log(meta)
  console.log(data)
}

All of the headers are the same String value as the HTTP Headers with one notable exception: Link. Link headers are pre-parsed for you and come through as an array of [url, options] tuples.

A link that looks like this:

Link: ; rel="next", ; rel="foo"; bar="baz"

… will look like this in the callback output:

  "Link" : [
    [
      "url1",
      {
        "rel" : "next"
      }
    ],
    [
      "url2",
      {
        "rel" : "foo",
        "bar" : "baz"
      }
    ]
  ]
}