Need help with dropbox_api?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

141 Stars 68 Forks MIT License 389 Commits 3 Opened issues


Ruby client library for Dropbox API v2

Services available


Need anything else?

Contributors list


Library for communicating with Dropbox API v2.


Add this line to your application's Gemfile:

gem 'dropbox_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install dropbox_api


Please, refer to this gem's custom Dropbox API documentation. Most of the time you'll be checking the available endpoints.

Unfortunately, the documentation at is disrecommended because it lacks some nice features that have been added with YARD plugins:

  • Each endpoint includes its tests right below the description, this works as an example of its usage.
  • All endpoints are shown as methods of the
    class, just as you will use them.

Basic set up

Authorize your application

Dropbox uses OAuth, in order to use this library from your application you'll have to get an authorization code.

Once you have it, just pass it on client initialization:"VofXAX8D...")
#=> #<:client ...>

Or set it as an ENV variable called

, for example:
#=> #<:client ...>

Note that setting an ENV variable is only a feasible choice if you're only using one account.

Option A: Get your access token from the website

The easiest way to obtain an access token is to get it from the Dropbox website. You just need to log in to Dropbox and refer to the developers section, go to My apps and select your application, you may need to create one if you haven't done so yet.

Under your application settings, find section OAuth 2. You'll find a button to generate an access token.

Option B: Use

You can obtain an authorization code with this library:

authenticator =, CLIENT_SECRET)
authenticator.authorize_url #=> ""

Now you need to open the authorization URL in your browser,

authorize the application and copy your code.

auth_bearer = authenticator.get_token(CODE) #=> #<:accesstoken ...>` auth_bearer.token #=> "VofXAX8D..."

Keep this token, you'll need it to initialize a DropboxApi::Client object


Standard OAuth 2 flow

This is what many web applications will use. The process is described in Dropbox's OAuth guide.

If you have a Rails application, you might be interested in this setup guide.

Performing API calls

Once you've initialized a client, for example:

client ="VofXAX8D...")
#=> #<:client ...>

You can perform an API call like this:

result = client.list_folder "/sample_folder"
#=> #<:results::listfolderresult>
#=> [#<:metadata::folder>, #<:metadata::file>]
#=> false

The instance of

we've initialized is the one you'll be using to perform API calls. You can check the class' documentation to find all available endpoints.

Large file uploads

If you need to upload files larger than 150MB the default

endpoint won't work. Instead, you need to start a upload session and upload the file in small chunks.

To make this easier, the method

will handle this for you, example:
client ="VofXAX8D...")
#=> #<:client ...>"large_file.avi") do |f|
  client.upload_by_chunks "/remote_path.txt", f

Check out the method documentation to find out all available options.


This gem depends on oauth2 and faraday.

It has official support for Ruby versions



After checking out the repo, run

to install dependencies. Then, run
for an interactive prompt that will allow you to experiment.


I recommend you to use a test account other than your main one.

We use VCR to record the HTTP calls to Dropbox, however we sometimes need to regenerate the cassettes. Let's take

as an example to show what would be the procedure to do so:
  1. Manually delete the existing cassettes in

  2. Run the task to build the scaffolding in your Dropbox account so the tests will pass. If it doesn't exist you may need to write it yourself, check the

    class to find all existing scaffold builders.
    DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER rake test:build_scaffold[list_folder]

    Note that you'll have to type

    rake test:build_scaffold\[list_folder\]
    if you use

    You can build all available scaffolds with just

    rake test:build_scaffold
  3. Run the tests and the cassettes will be written:

    DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER rspec spec/endpoints/files/list_folder_spec.rb

The OAuth bearer shouldn't have been recorded in the cassette and it should've been filtered. However, you may want to double check before pushing your updates to Github.

Tip: you can simply run

at the beginning of your work session so you don't need to prefix it in every command line.


Any help will be much appreciated. The easiest way to help is to implement one or more of the endpoints that are still pending. To see how the endpoints are implemented, check out the


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.