Skip to content
Box View
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status

A BoxView API wrapper. Built using the power of HTTParty to communicate with the BoxView API. The BoxView API has added some new features and improved documentation, this lib takes care of all of those new additions for you. You can learn more at the developer page. Note this product and API are still in beta, and likely to change in the future. Boxviewrb works with all available requests that are documented by BoxView at the time of writing.

Table of Contents


Add this line to your application's Gemfile:

gem 'boxview.rb'

And then execute:

$ bundle

Or install it yourself as:

$ gem install boxview.rb



Defining an api key is the only required configuration. To get your own API Key, visit Box and get a developer account. Then create a new Box View application. Scroll to the bottom of the application settings page to find your api key.

BoxView.api_key = "#{BOXVIEW_APIKEY}" # Example: 'gyheecmm6ckk8jutlowlzfh2tbg72kck'



See below for how to create a document using boxviewrb. Not all the paramaters used are required. The url is the only parameter that will be necessary in order to make a successful call with the BoxView API. Name refers to the name of the document. Non_SVG refers to whether you want to support browsers that cannot support svg. The Height and Width parameters refer to the size of a thumbnail that will give Box an early start to generating your thumbnail for you. You must still make a second request for a thumbnail, but it will be made available sooner upon request.

After this call is made, the BoxView API will return with a response. Boxviewrb will automatically have the document id available when the response is returned, call BoxView.document_id to retrieve it. If the call to BoxView fails, a specific error will be raised depending on what went wrong.

Required: url

Optional: name, non_svg, width and height

  url: '',
  name: 'chimpanzee',
  non_svg: true,
  width: 100,
  height: 100


If you have access to the actual file you want to upload to box, you can directly upload it via a multipart upload. This method requires the path to the file to be specified in order for it to send the file to box. If the filepath does not exist, an error will be thrown. The other params (name, thumbnail and non_svg) are the same as the create request params.

Required: filepath

Optional: name, non_svg, width and height

  filepath: '/Documents/sample.docx',
  name: 'sample',
  non_svg: true,
  width: 100,
  height: 100


This request will respond with a list of all the documents that are currently tied to the api key that has been supplied. Delete requests will remove documents from this list. This method returns the response untouched.



Returns the metadata for a single document based on a specified document id. If the document has successfully been generated by box, the status of the document will be 'done'. If not the status will be 'error'. The status is returned in the response when calling show.

Required: document_id document_id: '937778a1a54b4337a5351a78f7188a24'


Update the metadata of a single document based on a specified document id. Only the name can be updated at this time.

Required: document_id, name

  document_id: '937778a1a54b4337a5351a78f7188a24',
  name: 'recipes'


Removes a previously created document from the Box View servers. This request is destructive.

Required: document_id

BoxView::Document.delete document_id: '937778a1a54b4337a5351a78f7188a24'


A request to retrieve a thumbnail representation of a document. A document id must be specified in order to make the request. If the server response contains the response code 202 then the retry after attribute will be available when calling BoxView::Document.retry_after. This can be useful if Box is rate limiting.

Required: document_id, width and height

  document_id: '937778a1a54b4337a5351a78f7188a24',
  width: 100,
  height: 100


A request to retrieve a pdf or zip of the asset that was uploaded. The document will be retrieved as a pdf or zip. The zip contains compressed css/js/html that make up the converted document. This can be used in junction with viewerjs. This request defaults to zip if no type is specified.

Required: document_id, type

  document_id: '937778a1a54b4337a5351a78f7188a24',
  type: 'pdf'



Generating a document will give you a document id. Next you can create a session using this id. The session will begin the conversion process of the document. When Box is done converting your document it will be available to download through the assets method or the viewer url convenience method. A session expires after a set amount of time. You can set a duration or an expiration date for the session. If left blank, the session is set by box by default to expire in 60 minutes. Duration is marked in minutes. Expiration date is a timestamp. The variable is_downloadable refers to whether or not the box viewer will display a download button or not. If the server response contains the response code 202 then the retry after attribute will be available when calling BoxView::Session.retry_after.

After successfully generating a session, the session id will be available. You can either parse it out of the response that is returned, or just call BoxView.session_id.

Required: document_id

Optional: duration, expiration_date, is_downloadable

  document_id: '937778a1a54b4337a5351a78f7188a24',
  duration: 100,
  expiration_date: ( + 100.minutes),
  is_downloadable: true



Creating a webhook requires a URL that will be used as a the callback URL by the Box View API.

Required: url



Request the URL currently being used for webhooks.



Request that the webhook URL used by the API be deleted.


Convenience Methods

Never Expire

When generating a session if you want your session to last for a very long time (a thousand years) call this method.



Opens a default browser using the viewer url to view a BoxView converted document. Requires a session_id.


ViewerJS URL

This url can be used with viewerjs to display the assets without using the Box iframe or downloading the assets yourself. Requires a session_id.


Viewer URL

The url used in the view method. Can be used in an iframe to display the converted document. Requires a session_id.


Supported MIMETypes

Returns an array containing all the mimetypes that BoxView is known to support.


Supported File Extensions

Returns an array containing all the extensions of filetypes that BoxView is known to support.



  1. Fork it ([my-github-username]/boxviewrb/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


Vincent Taverna,,


boxviewrb is available under the MIT license. See the LICENSE file for more information.

You can’t perform that action at this time.