Ruby integration for Uploadcare


Uploadcare Ruby integration handles uploads and further operations with files by wrapping Upload and REST APIs.


Add this line to your application's Gemfile:

gem 'uploadcare-ruby'

And then execute:

$ bundle

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

Set your Uploadcare keys in config file or through environment variables UPLOADCARE_PUBLIC_KEY and UPLOADCARE_SECRET_KEY.

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/default_configuration.rb

export UPLOADCARE_PUBLIC_KEY=demopublickey
export UPLOADCARE_SECRET_KEY=demoprivatekey


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.

# Create API object
@api =

# Upload file
@file_to_upload ="your-file.png")

# => "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)

Entity object

Entities are representations of objects in Uploadcare cloud.


File entity, gotten from @api.file or @api.upload_one, contains its metadata.

@file = @api.file('8f64f313-e6b1-4731-96c0-6751f1e7a50a')
 "uuid"=>"8f64f313-e6b1-4731-96c0-6751f1e7a50a"} # stores file, returns updated metadata

@file.delete #deletes file. Returns updated metadata

Metadata of deleted files is stored permanently.


Uploadcare::Api::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::Api#file_list method.

@list = @api.file_list # => instance of Uploadcare::Api::FileList

This method accepts some options to controll which files should be fetched and how they should be fetched:

  • :limit — Controls page size. Accepts values from 1 to 1000, defaults to 100.
  • :stored — Can be either true or false. When true, file list will contain only stored files. When false — only not stored.
  • :removed — Can be either true or false. When true, file list will contain only removed files. When false — all except removed. Defaults to false.
  • :ordering — Controls the order of returned files. Available values: datetime_updated, -datetime_updated, size, -size. Defaults to datetime_uploaded. More info can be found here.
  • :from — Specifies the starting point for a collection. Resulting collection will contain files from the given value and to the end in a direction set by an ordering option. When files are ordered by datetime_updated in any direction, accepts either a DateTime object or an ISO 8601 string. When files are ordered by size, accepts non-negative integers (size in bytes). More info can be found here.

Options used to create a file list can be accessed through #options method. Note that, once set, they don't affect file fetching process anymore and are stored just for your convenience. That is why they are frozen.

options = {
  limit: 10,
  stored: true,
  ordering: '-datetime_uploaded',
  from: "2017-01-01T00:00:00",
@list = @api.file_list(options)


Groups are structures intended to organize sets of separate files. Each group is assigned UUID. Note, group UUIDs include a ~#{files_count} part at the end. That's a requirement of our API.

# group can be created from an array of Uploadcare files
@files_ary = [@file, @file2]
@files = @api.upload @files_ary
@group = @api.create_group @files


You can use webhooks to provide notifications about your uploads to target urls. This gem lets you create and manage webhooks.


Project provides basic info about the connected Uploadcare project. That object is also an Hashie::Mash, so every methods out of these will work.

@project = @api.project
# => #<Uploadcare::Api::Project collaborators=[], name="demo", pub_key="demopublickey", autostore_enabled=true>
# => "demo"

# => []
# while that one was empty, it usually goes like this:
# [{"email": [email protected], "name": "Collaborator"}, {"email": [email protected], "name": "Collaborator"}]

Uploadcare documentation
Upload API reference
REST API reference
Contributing guide
Security policy