Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Provides a simple ruby wrapper around the DocRaptor API
tree: c6cfdc7c93

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


This is a Ruby gem providing a simple wrapper around the DocRaptor API. DocRaptor is a web service that allows you to convert html to pdf or html to xls.


The gem will look for your api key in the ENV variable DOCRAPTOR_API_KEY. If it is not there, you can set it directly by calling:

DocRaptor.api_key "My API Key Here"

Once an API key is set, you can create a PDF document by calling:

DocRaptor.create(:document_content => content)

You might want to set other options in that hash:

  • :document_content - a string containing the content for creating the document
  • :document_url - a url to visit to get the content for creating the document
  • :document_type - "pdf" or "xls"; controls the type of document generated; default is "pdf"
  • :name - an identifier you can use for the document; shows up in doc logs; default is "default"
  • :test - test mode flag; set to true to while doing testing so the docs won't count against your monthly count; default is false
  • :prince_options - see (PDFs only)
  • :async - create the document asynchonously; default is false
  • :callback_url - a url that we will hit with a status once the asynchronous document has been fully processed

The only required parameter is one of :document_content or :document_url.

create will return an HTTParty response object, the body of which will be the new file (or errors, if the request was not valid).

create! will raise an exception instead of return errors if there is a failure of any sort in the document generation process. It otherwise works in the same way as create.

If the document is processed asynchronously, a status id will be returned as opposed to the contents of the document. You can then use to get the status of the document. You can pass in a URL to :callback_url to be called once an asynchronous job is complete. It will be passed a value of download_url which will contain a URL that when visited will provide you with your document. This option does nothing if :async is not true.

The create call can also take a block, like so:

DocRaptor.create(:document_content => content) do |file, response|
  #file is a tempfile holding the response body
  #reponse is the HTTParty response object

Async Doc Creation

To get the status of an async request, you can call:

# uses the id of the most recently created async job
# query some other async job and make it the "active" async job for the DocRaptor class

status_id is the value returned from DocRaptor.create when :async is true. If you have just created a document, status_id defaults to the last status_id received from DocRaptor. This will return a hash containing, at the very least, a key of status with a value of one of the following: {"completed", "failed", "killed", "queued", "working"}.

  • If the status is queued, no other information will be available.
  • If the status is working, there will be a human readable message contained in "message" that gives further details as to the state of the document.
  • If the status is complete there will be a key of "download_url" that will contain a 2 time use URL that, when visited, will provide your document.

There will also be a key of download_key that can be given to the function to obtain your document. If the status is killed, it means the system had to abort your document generation process for an unknown reason, most likely it was taking too long to generate. If the status is failed you can check the messages value for a message and the validation_errors value for a more detailed reason for the failure to generate your document.

To download an async document, you can visit the URL (download_url) provided via the status function or you can call:

# uses the key of the most recently checked async job which is complete
# use some other complete doc's download key

download_key is the value from the status hash of a call to DocRaptor.status of a completed job.

  • If you have just checked the status of a document and it is completed, download_key defaults to that of the document you just checked.

The download function works like DocRaptor.create in that you get back either an HTTParty response object or you can give it a block.


Check the examples directory for some simple examples. To make them work, you will need to have the docraptor gem installed (via bundler or gem install).

For more examples including a full rails example, check


Maintained by Expected Behavior

Released under the MIT license.

Something went wrong with that request. Please try again.