> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# Ruby API Client

> Ruby Uploadcare API client for Fast & Reliable File Uploads; File, Group, Project Operations; Video Conversion, & More.

Ruby integration handles uploads and file operations by wrapping Uploadcare
[Upload API](https://uploadcare.com/docs/api/upload/) and [REST API](https://uploadcare.com/docs/api/rest/). This
comprehensive API client lets you use most of the Uploadcare features from within
your Ruby app.

[Gem →](https://rubygems.org/gems/uploadcare-ruby)

[GitHub →](https://github.com/uploadcare/uploadcare-ruby)

## Features

Uploading ([Upload API](https://uploadcare.com/docs/api/upload/)):

* 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](https://uploadcare.com/docs/api/rest/)):

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

Image processing ([URL API](https://uploadcare.com/docs/api/url/)):

* 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 3.3+

Upgrading from v4.x? See the [migration guide](https://github.com/uploadcare/uploadcare-ruby/blob/main/MIGRATING_V5.md).

## Install

Add this line to your application's Gemfile:

```ruby
gem 'uploadcare-ruby'
```

And then execute:

```
bundle
```

If already not, create your project in [Uploadcare dashboard](https://app.uploadcare.com/) and copy
[your API keys](https://app.uploadcare.com/projects/-/api-keys/) from there.

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

```bash
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`](https://github.com/uploadcare/uploadcare-ruby/blob/main/lib/uploadcare.rb)

```ruby
# Preferred: explicit client
client = Uploadcare::Client.new(
  public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
  secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
)

# Alternative: global configuration (still supported)
Uploadcare.configure do |config|
  config.public_key = ENV.fetch('UPLOADCARE_PUBLIC_KEY')
  config.secret_key = ENV.fetch('UPLOADCARE_SECRET_KEY')
end
```

## Examples

### Quick start

```ruby
require 'uploadcare'

client = Uploadcare::Client.new(
  public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
  secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
)

file = File.open('image.png', 'rb') do |io|
  client.files.upload(io, store: 'auto')
end
```

### Upload API

#### Upload from URL

```ruby
file = client.files.upload_from_url("https://example.com/image.jpg", store: true)
puts file.cdn_url
```

#### Multipart upload (large files)

```ruby
File.open('big_file.bin', 'rb') do |io|
  file = client.uploads.multipart_upload(file: io, store: true)
  puts file.uuid
end
```

*View related scripts:* [post_multipart_start.rb](https://github.com/uploadcare/uploadcare-ruby/blob/main/api_examples/upload_api/post_multipart_start.rb), [post_multipart_complete.rb](https://github.com/uploadcare/uploadcare-ruby/blob/main/api_examples/upload_api/post_multipart_complete.rb)

### REST API

#### Get file info

```ruby
file = client.files.find(uuid: 'YOUR_FILE_UUID')
puts file.mime_type
```

#### Add a webhook

```ruby
webhook = client.webhooks.create(
  target_url: "https://example.com/callback",
  event: "file.uploaded",
  is_active: true
)
puts webhook.id
```

#### Search files

```ruby
results = client.files.search(query: "invoice", limit: 20)

results.each { |file| puts file.original_filename }
```

#### File tags

```ruby
client.file_tags.replace(uuid: "YOUR_FILE_UUID", tags: ["cat", "animal"])

client.file_tags.update(uuid: "YOUR_FILE_UUID", add: ["featured"], delete: ["cat"])

tags = client.file_tags.list(uuid: "YOUR_FILE_UUID")
```

> **Info**
>
> 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.

```ruby
@uc_file = File.open('your-file.png', 'rb') do |io|
  client.files.upload(io, store: true)
end

puts @uc_file.uuid
puts @uc_file.cdn_url
```

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.

### More upload methods

Uploadcare supports multiple ways to upload files:

```ruby
# Smart upload: accepts an IO, array of IOs, or a URL string
client.uploads.upload('https://example.com/image.jpg')

# Multiple files
client.uploads.upload([file1, file2], store: true)

# URL upload
client.files.upload_from_url('https://example.com/image.jpg', store: true)

# Multipart upload for large files
File.open('big_file.bin', 'rb') do |io|
  client.uploads.multipart_upload(file: io, store: true)
end
```

### Upload options

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

```ruby
client.uploads.upload(files, store: true)
client.files.upload_from_url(url, store: 'auto')
```

### Client

Most methods are available through a `Uploadcare::Client` instance:

```ruby
client.uploads.upload('https://example.com/image.jpg')
```

### Entity object

Entities are representations of objects in Uploadcare cloud.

#### File

File entity contains its metadata.

```ruby
@file = client.files.find(uuid: 'FILE_UUID')
# => #<Uploadcare::Resources::File ...>

# Metadata is read through accessor methods, not hash keys:
@file.uuid              # => "8f64f313-e6b1-4731-96c0-6751f1e7a50a"
@file.mime_type         # => "image/jpeg"
@file.size              # => 5345
@file.is_image          # => true
@file.is_ready          # => true
@file.original_filename # => "image.jpeg"
@file.datetime_uploaded # => "2020-01-16T15:03:14.676902Z"
@file.datetime_stored   # => "2020-01-16T15:03:15.315064Z"
@file.datetime_removed  # => nil
@file.url               # => "https://api.uploadcare.com/files/FILE_UUID/"
@file.cdn_url           # => "https://PROJECT_SUBDOMAIN.ucarecd.net/FILE_UUID/image.jpeg"
@file.content_info      # => { "mime" => { "mime" => "image/jpeg", "type" => "image", "subtype" => "jpeg" },
                        #      "image" => { "width" => 190, "height" => 183, "format" => "JPEG",
                        #                   "color_mode" => "RGB", "dpi" => nil, "orientation" => nil } }
@file.metadata          # => {}  custom key/value metadata you attach to the file
@file.appdata           # => {}  add-on results (virus scan, moderation, etc.)
```

> **Note**
>
> **Note:** `content_info` replaces the old `image_info` field and covers image dimensions, video duration/bitrate, and audio info.

> **Note**
>
> **Note:** `copy` is no longer available. Use `copy_to_local` or `copy_to_remote` instead.

```ruby
@file.copy_to_local(options: { store: true })
@file.copy_to_remote(target: "custom_storage")

@file.store #stores file, returns updated metadata

@file.delete #deletes file. Returns updated metadata
```

Metadata of deleted files is stored permanently.

#### FileList

`FileList` represents the whole collection of files (or a subset) and provides a way to iterate through it, making pagination transparent.
FileList objects can be created using `client.files.list`.

```ruby
@list = client.files.list(limit: 100)
@list.each { |file| puts file.uuid }

# Paginate
@list.next_page
@list.previous_page

# Load all pages
@all_files = @list.all
```

## Full documentation

Read the full documentation on [GitHub](https://github.com/uploadcare/uploadcare-ruby).