Ruby API Client

Ruby integration handles uploads and file operations by wrapping Uploadcare Upload API and REST API. This comprehensive API client lets you use most of the Uploadcare features from within your Ruby app.

Gem →

GitHub →


Uploading (Upload API):

  • Upload files from local storage and URLs (up to 5 TB)
  • Multipart uploading for large files
  • Uploading network to speed uploading jobs (like CDN)

File management (REST API):

  • Get file info and perform various operations (store/delete/copy) with them
  • Work with groups of files
  • Get info about account project
  • Manage webhooks
  • Convert documents
  • Encode and transform videos

Image processing (URL API):

  • Compression
  • Geometry
  • Colors
  • Definition
  • Image and text overlays
  • Rotations
  • Recognition
  • File info
  • Proxy (fetch)

Security features:

  • Secure authentication
  • Secure uploads (signed uploads)
  • Secure delivery (signed URLs)
  • Secure webhooks (signing secret)


  • Ruby 2.7+

Note that uploadcare-ruby 3.x is not backward compatible with 2.x.


Add this line to your application's Gemfile:

gem 'uploadcare-ruby'

And then execute:


If you use api_struct gem in your project, replace it with uploadcare-api_struct:

gem 'uploadcare-api_struct'

and run bundle install.

If already not, create your project in Uploadcare dashboard and copy your API keys from there.

Set your Uploadcare keys in config file or through environment variables:


Or configure your app yourself if you are using different way of storing keys. Gem configuration is available in Uploadcare.configuration. Full list of settings can be seen in lib/uploadcare.rb

# your_config_initializer_file.rb
Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'

Usage example

This section contains practical usage examples. Please note, everything that follows gets way more clear once you've looked through our docs.

Uploading and storing a single file

Using Uploadcare is simple, and here are the basics of handling files.

@file_to_upload ="your-file.png")

@uc_file = Uploadcare::Uploader.upload(@file_to_upload)

# => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"

# URL for the file, can be used with your website or app right away
# => ""

Your might then want to store or delete the uploaded file. Storing files could be crucial if you aren't using the “Automatic file storing” option for your Uploadcare project. If not stored manually or automatically, files get deleted within a 24-hour period.

# that's how you store a file
# => #<Uploadcare::Api::File ...

# and that works for deleting it
# => #<Uploadcare::Api::File ...


Uploadcare supports multiple ways to upload files:

# Smart upload - detects type of passed object and picks appropriate upload method

There are explicit ways to select upload type:

files = ['1.jpg'),'1.jpg']


# multipart upload - can be useful for files bigger than 10 mb

Upload options

You can override global :autostore option for each upload request:

@api.upload(files, store: true)
@api.upload_from_url(url, store: :auto)


Most methods are also available through Uploadcare::Api object:

# Same as Uploadcare::Uploader.upload

Entity object

Entities are representations of objects in Uploadcare cloud.


File entity contains its metadata.

@file = Uploadcare::File.file('FILE_ID_IN_YOUR_PROJECT')

@file.copy #copies file, returns a new (copied) file metadata #stores file, returns updated metadata

@file.delete #deletes file. Returns updated metadata

Metadata of deleted files is stored permanently.


Uploadcare::Entity::FileList represents the whole collection of files (or it's subset) and provides a way to iterate through it, making pagination transparent. FileList objects can be created using Uploadcare::Entity.file_list method.

@list = Uploadcare::Entity.file_list
# Returns instance of Uploadcare::Api::FileList
    # Array of Entity::File
# load last page of files
@files = @list.files
# load all files
@all_files = @list.load

Full documentation

Read the full documentation on GitHub.