Ruby Client

The Ruby client library provides convenient access to the API from applications written in the Ruby language.


To install the package:

gem install

Or add this to your app's Gemfile:

gem '', '~> 1.0'


  • Ruby 3+

Ruby 2.x is now considered end-of-life by the Ruby project. As a policy, does not support integrations which are considered end-of-life by their vendor.



There are multiple ways to authenticate to the API.

Global API Key

You can set an API key globally, like this:

Files.api_key = "my-key"

Per-Request API Key

Or, you can pass an API key per-request, in the Options hash at the end of every method. Like this:

Files::Group.list({}, api_key: "my-key")

That key will automatically be used for any followup actions that occur on models returned from the API.

User Session

Or, you can open a user session by calling Files::Session.create

session = Files::Session.create(username: "username", password: "password")

Then use it as follows:

Files::Group.list({}, session: session)

Or use if for all subsequent API calls globally like this:

Files.session = Files::Session.create(username: "username", password: "password")

Setting Global Options

You can set the following global options directly on the Files module:

  • Files.log_level - set to nil, info, or debug
  • Files.open_timeout - open timeout in seconds (default: 30)
  • Files.read_timeout - read timeout in seconds (default: 80)
  • Files.initial_network_retry_delay - initial retry delay in seconds (default: 0.5)
  • Files.max_network_retries - max retries (default: 3)
  • Files.max_network_retry_delay - max retry delay in seconds (default: 2)
  • Files.base_url - Set client to use your site subdomain if your site is configured to disable global acceleration. Otherwise, don't change this setting for production. For dev/CI, you can point this to the mock server.
  • Files.proxy - proxy configuration (uses Faraday format)

File Operations

The Files::File and Files::Dir models implement the standard Ruby API for File and Dir, respectively. (Note that the API uses the word Folder, not Dir, and Files::Dir is simply an alias for Files::Folder).

List root folder

Files::Folder.list_for("/").each do |file|
  puts file.path

Writing a file example

Files::upload_file("local.txt", "/remote.txt")"local.txt") do |read_file|"remote.txt", "w") do |write_file|

Reading a file example


Additional Object Documentation

Additional docs are available at and also in the docs/ subdirectory of this directory.

RDoc (YARD) Generated Documentation coming in the future

We hope to add RDoc/Yard documentation to a future release.

Getting Support

The team is happy to help with any SDK Integration challenges you may face.

Just email and we'll get the process started.