Build Status: Build Status

Mainted by:

RubyBox provides a simple, chainable, feature-rich client for Box’s 2.0 API.


RubyBox uses Box’s OAuth2 Implementaton, Here are the steps involved in authorizing a client:

1) Get the authorization url.

```ruby require ‘ruby-box’

session ={ client_id: ‘your-client-id’, client_secret: ‘your-client-secret’ })

authorize_url = session.authorize_url(‘https://redirect-url-in-app-settings’) ```

2) After redirecting to the authorize_url, exchange the code given for an access_token

```ruby @token = session.get_access_token(‘code-returned-to-redirect_url’) p ‘@token.token’ # the access token. p ‘@token.refresh_token’ # token that can be exchanged for a new access_token once the access_token expires.

refreshing token.

session ={ client_id: ‘your-client-id’, client_secret: ‘your-client-secret’, access_token: ‘original-access-token’ })

you need to persist this somehow. the refresh token will change every time you use it

@token = session.refresh_token(‘your-refresh-token’) save_me_somehow(@token.refresh_token) ```

3) Create a client using a session initialized with the access_token.

```ruby require ‘ruby-box’

session ={ client_id: ‘your-client-id’, client_secret: ‘your-client-secret’, access_token: ‘access-token’ })

client = ```


Once you’ve created a client, you can start interacting with the Box API. What follows are some basic examples of RubyBox’s usage.


Please note that using a file/folder path is extremely inefficient, as it causes the gem to traverse the directory structure recursively querying each folder in turn. Prefer the _by_id methods where possible for single-request access.


Files and Folders are subclasses of Item. Folder contents (i.e. files and folders inside that folder) are retrieved in a mini-format when the Folder instance is loaded.

There are two caveats to this:

Only some fields are available

a File mini looks like this:

{ "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg" } a Folder mini looks like this:

{ "type":"folder", "id":"301415432", "sequence_id":"0", "name":"my first sub-folder" }

Requests to fields other than the above (e.g. file.size) will cause a one-off hit to the api, so take care when iterating over folder contents lest a single application method result in hundreds of api hits and take forever to complete.

This can be mitigated by passing a list of extra fields you want to fetch into the .items method:

ruby folder = client.folder_by_id(@folder_id) # retrieve size, created_at, and description for all items in this directory detailed_items = folder.items(@item_limit, @offset, ['size', 'created_at', 'description'])

Note: only the type and id fields are included in addition to whatever you specify using the above method, so you must be explicit.


  • Listing items in a folder:

ruby files = client.folder('/image_folder').files # all files in a folder using a path. files = client.folder(@folder_id).files # all files in a folder using an id. folders = client.root_folder.folders # all folders in the root directory. files_and_folders = client.folder('files').items # all files and folders in /files

  • Creating a folder:

ruby client.folder_by_id(@folder_id).create_subfolder('subfolder') # using an id. client.folder('image_folder').create_subfolder('subfolder') # using a path.

  • Setting the description on a folder:

ruby folder = client.folder('image_folder') # using a path. folder.description = 'Description on Folder' folder.update

  • Listing the comments in a discussion surrounding a folder.

ruby folder = client.folder('image_folder') # lookups by id are more efficient discussion = folder.discussions.first discussion.comments.each {|comment| p comment.message}

  • Creating a shared link for a folder.

ruby folder = client.folder('image_folder').create_shared_link # lookups by id are more efficient p folder.shared_link['url'] #


  • Fetching a file’s meta information.

ruby file = client.file('/image_folder/an-image.jpg')# lookups by id are more efficient file = client.file(@file_id) p p file.created_at

  • Uploading a file to a folder.

ruby file = client.upload_file('./LICENSE.txt', '/license_folder') # lookups by id are more efficient file = client.upload_file_by_folder_id('./LICENSE.txt', @folder_id)

  • Downloading a file.

```ruby f = open(‘./LOCAL.txt’, ‘w+’) f.write( client.file(‘/license_folder/LICENSE.txt’).download ) f.close()

Or you can fetch by, which is more efficient:

f = open(‘./LOCAL.txt’, ‘w+’) f.write( client.file_by_id(@file_id).download ) # lookups by id are more efficient f.close()

You can also grab the raw url with


Note that this URL is not persistent. Clients will need to follow the url immediately in order to

# actually download the file ```

  • Deleting a file.

ruby client.file_by_id(@file_id).delete # this client.file('/license_folder/LICENSE.txt').delete

  • Displaying comments on a file.

```ruby comments = client.file(‘/image_folder/an-image.jpg’).comments # lookups by id are more efficient comments = client.file_by_id(@file_id).comments

comments.each do |comment| p comment.message end ```

  • Creating a shared link for a file.

ruby file = client.file('/image_folder/an-image.jpg').create_shared_link file = client.file_by_id(@file_id).create_shared_link # using an id p file.shared_link.url #

  • Copying a file to another folder.


file = client.file(‘/one_folder/cow_folder/an-image.jpg’) folder = client.folder(‘image_folder’)

lookups by id are more efficient

file = client.file_by_id(@file_id) folder = client.folder_by_id(@folder_id)

file.copy_to(folder) ```

  • Moving a file to another folder.


file = client.file(‘/one_folder/cow_folder/an-image.jpg’) folder = client.folder(‘image_folder’)

lookups by id are more efficient

file = client.file_by_id(@file_id) folder = client.folder_by_id(@folder_id)

file.move_to(folder) ```

  • Adding a comment to a file.

ruby file = client.file('/image_folder/an-image.jpg') # path file = client.file_by_id(@file_id) # id comment = file.create_comment('Hello World!')

You can use RubyBox’s search method to return files and folders that match a given query.

ruby items ='image') items.each do |item| p "type=#{item.type} name=#{}" end


You can use RubyBox’s event_response method to return an EventResponse that can be used to process any incoming events.

ruby eresp = client.event_response eresp.chunk_size eresp.next_stream_position do |ev| p "type=#{ev.event_id} type=#{ev.event_type} user=#{}" end


  • This must be manually enabled for your account by Box Staff. Contact [email protected] for access. [ More Info ] (

ruby session ={ client_id: 'your-client-id', client_secret: 'your-client-secret', access_token: 'original-access-token' , as_user: 'your-users-box-id' }) Users ——

Current User Info

ruby me =

Current User’s enterprise

ruby me =

An array of Ruby:Box users in an enterprise (Supports Filtering, Limit and Offset)

ruby users = client.users

  • Remeber the API filters “name” and “login” by the start of the string. ie: to get “[email protected]” an approriate filter term would be “sean”

ruby users = client.users("sean" , 10 , 1)


Contributing to ruby-box

RubyBox does not yet support all of Box’s API Version 2.0 functionality, be liberal with your contributions.

  • Rename account.example to account.yml and fill in your Box credentials
  • Type bundle install
  • Type rake.. tests should pass
  • Add a failing test
  • Make it pass
  • Submit a pull request


Copyright (c) 2012 See LICENSE.txt for further details.