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 →

Features

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)

Requirements

Ruby 2.7+

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

Install

Add this line to your application’s Gemfile:

1 gem 'uploadcare-ruby'

And then execute:

bundle

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:

$ export UPLOADCARE_PUBLIC_KEY=$YOUR_PUBLIC_KEY
$ export UPLOADCARE_SECRET_KEY=$YOUR_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.rb

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

Examples

Quick start

1 require 'uploadcare'
2 
3 Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
4 Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
5 
6 source_file = File.open('image.png')
7 Uploadcare::Uploader.upload(source_file, store: 'auto')

Tip: For production use, configure your keys via environment variables, for example: Uploadcare.config.public_key = ENV['UPLOADCARE_PUBLIC_KEY']

Upload API

Upload from URL

1 require 'uploadcare'
2 
3 Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
4 Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
5 
6 file = Uploadcare::Uploader.upload_from_url("https://placekitten.com/96/139")
7 puts file.cdn_url

View full script: post_from_url.rb

Multipart upload (large files)

1 require 'uploadcare'
2 
3 Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
4 Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
5 
6 Uploadcare::Uploader.multipart_upload(File.open("big_file.bin"))

View related scripts: post_multipart_start.rb, post_multipart_complete.rb

REST API

Get file info

1 require 'uploadcare'
2 
3 Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
4 Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
5 
6 info = Uploadcare::File.info("YOUR_FILE_UUID")
7 puts info["mime_type"]

View full script: get_files_uuid.rb

Add a webhook

1 require 'uploadcare'
2 
3 Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
4 Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
5 
6 webhook = Uploadcare::Webhook.subscribe("https://example.com/callback", is_active: true)
7 puts webhook["id"]

View full script: post_webhooks.rb

Note: All examples assume you configured your API keys. Replace placeholders with your actual keys, or set them via environment variables.

Uploading and storing a single file

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

1 @file_to_upload = File.open("your-file.png")
2 
3 @uc_file = Uploadcare::Uploader.upload(@file_to_upload)
4 
5 @uc_file.uuid
6 # => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
7 
8 # URL for the file, can be used with your website or app right away
9 @uc_file.cdn_url
10 # => "https://2ilqpaxwma.ucarecd.net/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"

You 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.

1 # that's how you store a file
2 @uc_file.store
3 # => #<Uploadcare::Api::File ...
4 
5 # and that works for deleting it
6 @uc_file.delete
7 # => #<Uploadcare::Api::File ...

More upload methods

Uploadcare supports multiple ways to upload files:

1 # Smart upload - detects type of passed object and picks appropriate upload method
2 Uploadcare::Uploader.upload('https://placekitten.com/96/139')

There are explicit ways to select upload type:

1 files = [File.open('1.jpg'), File.open('1.jpg']
2 Uploadcare::Uploader.upload_files(files)
3 
4 Uploadcare::Uploader.upload_from_url('https://placekitten.com/96/139')
5 
6 # multipart upload - can be useful for files bigger than 10 mb
7 Uploadcare::Uploader.multipart_upload(File.open('big_file.bin'))

Upload options

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

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

Api

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

1 # Same as Uploadcare::Uploader.upload
2 Uploadcare::Api.upload('https://placekitten.com/96/139')

Entity object

Entities are representations of objects in Uploadcare cloud.

File

File entity contains its metadata.

1 @file = Uploadcare::File.file('FILE_UUID')
2 {"datetime_removed"=>nil,
3  "datetime_stored"=>"2020-01-16T15:03:15.315064Z",
4  "datetime_uploaded"=>"2020-01-16T15:03:14.676902Z",
5  "image_info"=>
6   {"color_mode"=>"RGB",
7    "orientation"=>nil,
8    "format"=>"JPEG",
9    "sequence"=>false,
10    "height"=>183,
11    "width"=>190,
12    "geo_location"=>nil,
13    "datetime_original"=>nil,
14    "dpi"=>nil},
15  "is_image"=>true,
16  "is_ready"=>true,
17  "mime_type"=>"image/jpeg",
18  "original_file_url"=>
19   "https://PROJECT_SUBDOMAIN.ucarecd.net/FILE_UUID/imagepng.jpeg",
20  "original_filename"=>"image.png.jpeg",
21  "size"=>5345,
22  "url"=>
23   "https://api.uploadcare.com/files/FILE_UUID/",
24  "uuid"=>"8f64f313-e6b1-4731-96c0-6751f1e7a50a"}
25 
26 @file.copy #copies file, returns a new (copied) file metadata
27 
28 @file.store #stores file, returns updated metadata
29 
30 @file.delete #deletes file. Returns updated metadata

Metadata of deleted files is stored permanently.

FileList

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.

1 @list = Uploadcare::Entity.file_list
2 # Returns instance of Uploadcare::Api::FileList
3 <Hashie::Mash
4   next=nil
5   per_page=100
6   previous=nil
7   results=[
8     # Array of Entity::File
9   ]
10   total=8>
11 # load last page of files
12 @files = @list.files
13 # load all files
14 @all_files = @list.load

Full documentation

Read the full documentation on GitHub.

$	export UPLOADCARE_PUBLIC_KEY=$YOUR_PUBLIC_KEY
$	export UPLOADCARE_SECRET_KEY=$YOUR_SECRET_KEY

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

1	require 'uploadcare'
2
3	Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
4	Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
5
6	source_file = File.open('image.png')
7	Uploadcare::Uploader.upload(source_file, store: 'auto')

1	@file_to_upload = File.open("your-file.png")
2
3	@uc_file = Uploadcare::Uploader.upload(@file_to_upload)
4
5	@uc_file.uuid
6	# => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
7
8	# URL for the file, can be used with your website or app right away
9	@uc_file.cdn_url
10	# => "https://2ilqpaxwma.ucarecd.net/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"

1	# that's how you store a file
2	@uc_file.store
3	# => #<Uploadcare::Api::File ...
4
5	# and that works for deleting it
6	@uc_file.delete
7	# => #<Uploadcare::Api::File ...

1	# Smart upload - detects type of passed object and picks appropriate upload method
2	Uploadcare::Uploader.upload('https://placekitten.com/96/139')

1	files = [File.open('1.jpg'), File.open('1.jpg']
2	Uploadcare::Uploader.upload_files(files)
3
4	Uploadcare::Uploader.upload_from_url('https://placekitten.com/96/139')
5
6	# multipart upload - can be useful for files bigger than 10 mb
7	Uploadcare::Uploader.multipart_upload(File.open('big_file.bin'))

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

1	# Same as Uploadcare::Uploader.upload
2	Uploadcare::Api.upload('https://placekitten.com/96/139')

1	@file = Uploadcare::File.file('FILE_UUID')
2	{"datetime_removed"=>nil,
3	"datetime_stored"=>"2020-01-16T15:03:15.315064Z",
4	"datetime_uploaded"=>"2020-01-16T15:03:14.676902Z",
5	"image_info"=>
6	{"color_mode"=>"RGB",
7	"orientation"=>nil,
8	"format"=>"JPEG",
9	"sequence"=>false,
10	"height"=>183,
11	"width"=>190,
12	"geo_location"=>nil,
13	"datetime_original"=>nil,
14	"dpi"=>nil},
15	"is_image"=>true,
16	"is_ready"=>true,
17	"mime_type"=>"image/jpeg",
18	"original_file_url"=>
19	"https://PROJECT_SUBDOMAIN.ucarecd.net/FILE_UUID/imagepng.jpeg",
20	"original_filename"=>"image.png.jpeg",
21	"size"=>5345,
22	"url"=>
23	"https://api.uploadcare.com/files/FILE_UUID/",
24	"uuid"=>"8f64f313-e6b1-4731-96c0-6751f1e7a50a"}
25
26	@file.copy #copies file, returns a new (copied) file metadata
27
28	@file.store #stores file, returns updated metadata
29
30	@file.delete #deletes file. Returns updated metadata

1	@list = Uploadcare::Entity.file_list
2	# Returns instance of Uploadcare::Api::FileList
3	<Hashie::Mash
4	next=nil
5	per_page=100
6	previous=nil
7	results=[
8	# Array of Entity::File
9	]
10	total=8>
11	# load last page of files
12	@files = @list.files
13	# load all files
14	@all_files = @list.load