> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# Ruby on Rails API client

> Ruby on Rails Uploadcare API client for fast & reliable file uploads; file, group, project operations; video conversion, & more.

Ruby on Rails integration handles uploads and file operations by wrapping
[uploadcare-ruby gem](/docs/integrations/ruby/). It will let you use most of
the Uploadcare features from within your Ruby on Rails app.

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

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

## Features

Gem features:

* [File uploader](https://uploadcare.com/products/file-uploader/)
* [Image processing](https://uploadcare.com/cdn/image-processing/)
* Uploadcare API interfaces

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/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](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+
* Ruby on Rails 7.2+

## Install

### Using Gemfile

Add this line to your application's Gemfile:

```ruby
gem "uploadcare-rails", "~> 5.0"
```

And then execute:

```console
bundle install
```

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

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

and run `bundle install`.

### Using command line

```console
gem install uploadcare-rails
```

## Usage

### Configuration

To start using Uploadcare API you just need to set your [API keys](https://app.uploadcare.com/projects/-/api-keys/)
(public key and secret key).
These keys can be set as ENV variables using the `export` directive:

```console
export UPLOADCARE_PUBLIC_KEY=YOUR_PUBLIC_KEY
export UPLOADCARE_SECRET_KEY=YOUR_SECRET_KEY
```

Or you can use popular gems like `dotenv-rails` for setting ENV variables.
You must set the gem before `uploadcare-rails` like this:

```ruby
gem "dotenv-rails", require: "dotenv/rails-now", groups: [:development, :test]
gem "uploadcare-rails", "~> 5.0"
```

> **Warning**
>
> **Warning:** `require: "dotenv/rails-now"` is very important!

Run the config generator command to generate a configuration file:

```console
rails g uploadcare_config
```

The generator will create a new file at `config/uploadcare.yml`.

The public key must be specified to use File Upload. For an ENV-based setup, keep
the environment sections and set the keys in `config/uploadcare.yml`:

```yaml
# config/uploadcare.yml
default: &default
  public_key: <%= ENV.fetch("UPLOADCARE_PUBLIC_KEY") %>
  secret_key: <%= ENV.fetch("UPLOADCARE_SECRET_KEY") %>
  store_files_after_save: true
  delete_files_after_destroy: true
  cache_files: true
  locale: en

development:
  <<: *default

test:
  <<: *default

production:
  <<: *default
```

You can also configure programmatically in an initializer:

```ruby
Uploadcare::Rails.configure do |config|
  config.public_key = ENV.fetch("UPLOADCARE_PUBLIC_KEY")
  config.secret_key = ENV.fetch("UPLOADCARE_SECRET_KEY")
  config.store_files_after_save = true
  config.delete_files_after_destroy = true
  config.cache_files = true
  config.locale = "en"
end
```

Then you can configure all global variables such as files storing/caching, deleting files, etc. Full list of available options is listed in the file itself.

### Model

Use `has_uploadcare_file` for a single file and `has_uploadcare_files` for a group of files:

```ruby
class Post < ApplicationRecord
  has_uploadcare_file :picture
  has_uploadcare_files :attachments
end
```

### View

Add the File Uploader to your layout:

```erb
<%= uploadcare_include_tag %>
```

Use the form helpers to render file upload fields:

```erb
<%= form_with model: @post do |f| %>
  <%= f.uploadcare_file_field :picture %>
  <%= f.uploadcare_files_field :attachments %>
<% end %>
```

### REST API

Access the Uploadcare REST API directly via the client:

```ruby
client = Uploadcare::Rails.client

# Get file info
file = client.files.find(uuid: "YOUR_FILE_UUID")

# Store a file
client.files.batch_store(uuids: ["YOUR_FILE_UUID"])

# Delete a file
client.files.batch_delete(uuids: ["YOUR_FILE_UUID"])

# Search files
results = client.files.search(query: "invoice")

# Manage file tags
client.file_tags.update(uuid: "YOUR_FILE_UUID", add: ["featured"], delete: ["draft"])
```

## Full documentation

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