uploadcare-ruby 5.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfba74b1784392911f6d3ced082ef949c314128aeba804958a54344b4a62b094
-  data.tar.gz: e193a1d8260e99b44b7b903fae7497644decb72efeef206350bd76062e226579
+  metadata.gz: b0a3dc13f1f548e3f3083128b65c9df35524321b9ab73bff80b8eae0e6d52e0e
+  data.tar.gz: fe8b13b6f891f938aabe9d1fe39875981662c4f3f8e66b4eb234b9daf884a734
 SHA512:
-  metadata.gz: bbfa444e6a5716c7539baf69c35711b2f16a79628376779289d6428732057a0906981476664c2f0e1a7a6a535ae8a9ceed9cf8ee5507e39b70a7a235a54e587e
-  data.tar.gz: bb9708224d02016fa9b16df4104396a784f89bad12cdb5d84d601b4ffaf524e68f9ee2bb21899d16c0d8c93c78ff5463a277c40cbfd84efde9843ba7ddc93657
+  metadata.gz: 54cbc1ab6d88ee5f08c8cbb022d69417ffc2b064897f4db815582b3f997e143c943b178d44b3afc340b5307cb747cd7d5b7ba3a08e01b7026d99649a575cb62d
+  data.tar.gz: da4e93044e29484359810c3bcda60e720067f2add3de07f0666c7e94bda4d95c243d96c6c832b0f53f2aad62d2b902b8d2169d1e4c0e4a929514dc7eaf74152d

data/.github/workflows/gem-push.yml

@@ -7,13 +7,15 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
 
     steps:
       - uses: actions/checkout@v5
 
       - name: Release Gem
         if: contains(github.ref, 'refs/tags/v')
-        uses: cadwallion/publish-rubygems-action@master
+        uses: cadwallion/publish-rubygems-action@94a6f4cd5350581749c569b5001eecc864e3ad0b # v1.1.0
         env:
           GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
           RUBYGEMS_API_KEY: ${{secrets.RUBYGEMS_API_KEY}}

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 5.1.0 — 2026-09-06
+
+### Added
+
+* Search files through `client.files.search` with full-text, UUID, exact, metadata, tag, range, and image filters,
+  sorting, highlights, `include=appdata`, and POST-aware pagination that preserves the original search options.
+* Manage per-file tags through `client.file_tags` with list, replace, and atomic add/delete operations.
+* Apply tags while uploading files directly, in batches, from URLs, or through multipart uploads.
+* Read tags from file resources returned by the REST API.
+* Call the raw REST file-search and file-tag endpoints through `client.api.rest` when exact endpoint parity is needed.
+
+## 5.0.1 — 2026-06-09
+
+### Fixed
+
+* Upload API requests now send the SDK-generated `User-Agent` instead of Faraday's default header.
+* Multipart upload part requests to presigned URLs now include the same SDK-generated `User-Agent`.
+
 ## 5.0.0 — 2026-05-17
 
 v5 is stable.

data/MIGRATING_V5.md

@@ -27,7 +27,7 @@ The examples expect `UPLOADCARE_PUBLIC_KEY` and `UPLOADCARE_SECRET_KEY` to come
 ## Recommended Migration Order
 
 1. Introduce explicit `Uploadcare::Client` instances in your application.
-2. Move app-facing code to `client.files`, `client.groups`, `client.uploads`, `client.project`, `client.webhooks`, `client.file_metadata`, `client.addons`, and `client.conversions`.
+2. Move app-facing code to `client.files`, `client.groups`, `client.uploads`, `client.project`, `client.webhooks`, `client.file_metadata`, `client.file_tags`, `client.addons`, and `client.conversions`.
 3. Keep `client.api.rest` and `client.api.upload` only where you need raw endpoint parity.
 4. Audit return-type and error-handling assumptions.
 5. Remove any app code that depends on internal transport classes.
@@ -201,6 +201,7 @@ These top-level resource constants still exist:
 - `Uploadcare::Project`
 - `Uploadcare::Webhook`
 - `Uploadcare::FileMetadata`
+- `Uploadcare::FileTags`
 - `Uploadcare::DocumentConversion`
 - `Uploadcare::VideoConversion`
 

data/README.md

@@ -27,6 +27,7 @@ The gem is built around:
 - [Multi-Account Usage](#multi-account-usage)
 - [Uploads](#uploads)
 - [Files](#files)
+- [File Tags](#file-tags)
 - [Groups](#groups)
 - [Project](#project)
 - [Metadata](#metadata)
@@ -87,6 +88,7 @@ This is the default API you should use in applications:
 - `client.project`
 - `client.webhooks`
 - `client.file_metadata`
+- `client.file_tags`
 - `client.addons`
 - `client.conversions`
 
@@ -262,7 +264,12 @@ remote_file = client.uploads.upload("https://example.com/image.jpg", store: true
 
 ```ruby
 file = File.open("photo.jpg", "rb") do |io|
-  client.files.upload(io, store: true, metadata: { subsystem: "avatars" })
+  client.files.upload(
+    io,
+    store: true,
+    metadata: { subsystem: "avatars" },
+    tags: ["avatar", "profile"]
+  )
 end
 ```
 
@@ -274,7 +281,7 @@ files = [
   File.open("photo-2.jpg", "rb")
 ]
 
-uploaded = client.uploads.upload(files, store: true)
+uploaded = client.uploads.upload(files, store: true, tags: ["gallery", "batch"])
 
 files.each(&:close)
 ```
@@ -284,7 +291,11 @@ files.each(&:close)
 Synchronous:
 
 ```ruby
-file = client.files.upload_from_url("https://example.com/image.jpg", store: true)
+file = client.files.upload_from_url(
+  "https://example.com/image.jpg",
+  store: true,
+  tags: ["remote", "example"]
+)
 ```
 
 Async:
@@ -306,7 +317,12 @@ Polling options for synchronous URL uploads:
 
 ```ruby
 File.open("large-video.mp4", "rb") do |io|
-  file = client.uploads.multipart_upload(file: io, store: true, threads: 4) do |progress|
+  file = client.uploads.multipart_upload(
+    file: io,
+    store: true,
+    threads: 4,
+    tags: ["video", "multipart"]
+  ) do |progress|
     uploaded = progress[:uploaded]
     total = progress[:total]
     puts "#{uploaded}/#{total}"
@@ -342,6 +358,7 @@ Common upload options:
 
 - `store: true | false | "auto"`
 - `metadata: { key: value }`
+- `tags: ["tag-1", "tag_2"]`
 - `signature: "..."`
 - `expire: unix_timestamp`
 - `async: true` for URL uploads
@@ -389,6 +406,50 @@ Filters and API parameters can still be passed through:
 files = client.files.list(stored: true, removed: false, limit: 100)
 ```
 
+### Search files
+
+Search across filenames, file UUIDs, metadata, and detected MIME types:
+
+```ruby
+matches = client.files.search(
+  query: "invoice",
+  is_image: false,
+  sort: ["-datetime_uploaded"],
+  limit: 20
+)
+
+puts "Found #{matches.total} files"
+matches.each do |file|
+  puts file.original_filename
+  puts file.highlight
+end
+```
+
+Search accepts full-text `query` and field-specific `phrase` criteria, exact matches, ranges, and tag filters. All
+top-level criteria are combined with AND:
+
+```ruby
+matches = client.files.search(
+  phrase: { original_filename: "report" },
+  exact: {
+    detected_mime_type: ["application/pdf"],
+    "metadata[department]" => ["finance"]
+  },
+  datetime_uploaded: { gte: "2026-01-01T00:00:00Z" },
+  size: { lte: 10 * 1024 * 1024 },
+  tags: { all: ["approved"], none: ["archived"] },
+  include: "appdata"
+)
+```
+
+`limit`, `offset`, and `include` are sent as URL query parameters; search criteria are sent in the JSON body. Search
+responses are `Uploadcare::Collections::FileSearchResult` objects and support `next_page`, `previous_page`, and `all`
+like ordinary file lists. Subsequent pages automatically resend the original search criteria. Full-text values must be
+at least four characters; use `exact` for shorter values. A field cannot appear in both `phrase` and `exact`, and every
+request needs at least one search condition. `limit` accepts 1–100 results, while `offset + limit` cannot exceed 1,000.
+For filter-only searches, pass an explicit `sort` for deterministic ordering. `fuzziness: true` enables typo-tolerant
+matching but increases latency. Newly uploaded files may take a short time to appear in the search index.
+
 ### Resource operations
 
 ```ruby
@@ -424,6 +485,43 @@ copied = file.copy_to_local(options: { store: true })
 remote_url = file.copy_to_remote(target: "custom_storage")
 ```
 
+File responses expose the ordered tag list through `file.tags` when the field is present.
+
+## File Tags
+
+Tags can be attached during direct, URL, batch, and multipart uploads with the `tags:` option. The SDK normalizes tags to lowercase, strips surrounding whitespace, discards blank tags, removes duplicates while preserving order, and validates the platform limits.
+Upload responses do not include tags; use `client.file_tags.list` or reload the file through the REST API to read them.
+
+Read or replace the complete tag list:
+
+```ruby
+tags = client.file_tags.list(uuid: file.uuid)
+
+change = client.file_tags.replace(
+  uuid: file.uuid,
+  tags: ["approved", "Summer"]
+)
+
+puts change.tags
+puts change.added
+puts change.deleted
+```
+
+Mutation responses expose the resulting ordered `tags`, the tags actually `added`, and the tags actually `deleted`.
+Replacing with the same normalized set is safe and reports no additions or deletions.
+
+Add and delete tags atomically (deletions are applied first):
+
+```ruby
+change = client.file_tags.update(
+  uuid: file.uuid,
+  add: ["featured"],
+  delete: ["draft"]
+)
+```
+
+Passing an empty array to `replace` clears all tags. Tags may contain Latin letters, digits, hyphens, underscores, and dots; each tag is limited to 100 characters and each file to 50 tags.
+
 ## Groups
 
 Create a group:
@@ -608,10 +706,14 @@ Upload API:
 
 ```ruby
 File.open("photo.jpg", "rb") do |io|
-  client.api.upload.files.direct(file: io, store: true)
+  client.api.upload.files.direct(file: io, store: true, tags: ["photo", "example"])
 end
 
-client.api.upload.files.from_url(source_url: "https://example.com/image.jpg", async: true)
+client.api.upload.files.from_url(
+  source_url: "https://example.com/image.jpg",
+  async: true,
+  tags: ["remote", "example"]
+)
 client.api.upload.groups.create(files: ["uuid-1", "uuid-2"])
 ```
 

data/api_examples/README.md

@@ -21,14 +21,15 @@ Optional environment variables:
 
 Verification:
 
-- Verified against a real Uploadcare demo account on `2026-03-16`
-- All canonical scripts in `api_examples/rest_api` and `api_examples/upload_api` executed successfully
+- The endpoint suite was verified against a real Uploadcare demo account on `2026-08-07`.
+- Run changed examples against a disposable project before release; they create and remove temporary resources.
 
 ## REST API 0.7
 
 | Endpoint | Example file | Notes |
 | --- | --- | --- |
 | `GET /files/` | `api_examples/rest_api/get_files.rb` | Uses `client.files.list` |
+| `POST /files/search/` | `api_examples/rest_api/post_files_search.rb` | Uses `client.files.search` with a UUID lookup |
 | `PUT /files/{uuid}/storage/` | `api_examples/rest_api/put_files_uuid_storage.rb` | Uses `file.store` |
 | `DELETE /files/{uuid}/storage/` | `api_examples/rest_api/delete_files_uuid_storage.rb` | Uses `file.delete` |
 | `GET /files/{uuid}/` | `api_examples/rest_api/get_files_uuid.rb` | Uses `client.files.find` |
@@ -40,6 +41,9 @@ Verification:
 | `GET /files/{uuid}/metadata/{key}/` | `api_examples/rest_api/get_files_uuid_metadata_key.rb` | Uses `client.file_metadata.show` |
 | `PUT /files/{uuid}/metadata/{key}/` | `api_examples/rest_api/put_files_uuid_metadata_key.rb` | Uses `client.file_metadata.update` |
 | `DELETE /files/{uuid}/metadata/{key}/` | `api_examples/rest_api/delete_files_uuid_metadata_key.rb` | Uses `client.file_metadata.delete` |
+| `GET /files/{uuid}/tags/` | `api_examples/rest_api/get_files_uuid_tags.rb` | Uses `client.file_tags.list` |
+| `PUT /files/{uuid}/tags/` | `api_examples/rest_api/put_files_uuid_tags.rb` | Uses `client.file_tags.replace` |
+| `PATCH /files/{uuid}/tags/` | `api_examples/rest_api/patch_files_uuid_tags.rb` | Uses `client.file_tags.update` |
 | `GET /groups/` | `api_examples/rest_api/get_groups.rb` | Uses `client.groups.list` |
 | `GET /groups/{uuid}/` | `api_examples/rest_api/get_groups_uuid.rb` | Uses `client.groups.find` |
 | `DELETE /groups/{uuid}/` | `api_examples/rest_api/delete_groups_uuid.rb` | Uses `group.delete` |
@@ -66,11 +70,11 @@ Verification:
 
 | Endpoint | Example file | Notes |
 | --- | --- | --- |
-| `POST /base/` | `api_examples/upload_api/post_base.rb` | Uses raw upload API |
-| `POST /multipart/start/` | `api_examples/upload_api/post_multipart_start.rb` | Starts and completes a real multipart upload |
+| `POST /base/` | `api_examples/upload_api/post_base.rb` | Uses raw upload API with upload-time tags |
+| `POST /multipart/start/` | `api_examples/upload_api/post_multipart_start.rb` | Starts and completes a real multipart upload with tags |
 | `PUT <presigned-url-x>` | `api_examples/upload_api/put_multipart_part.rb` | Uploads one part via gem multipart helper |
 | `POST /multipart/complete/` | `api_examples/upload_api/post_multipart_complete.rb` | Completes a real multipart upload |
-| `POST /from_url/` | `api_examples/upload_api/post_from_url.rb` | Uses raw upload API |
+| `POST /from_url/` | `api_examples/upload_api/post_from_url.rb` | Uses raw upload API with upload-time tags |
 | `GET /from_url/status/` | `api_examples/upload_api/get_from_url_status.rb` | Starts async upload then checks status |
 | `GET /info/` | `api_examples/upload_api/get_info.rb` | Uses raw upload API |
 | `POST /group/` | `api_examples/upload_api/post_group.rb` | Uses raw upload API |

data/api_examples/rest_api/get_files_uuid_tags.rb

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../support/run_rest_example'

data/api_examples/rest_api/patch_files_uuid_tags.rb

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../support/run_rest_example'

data/api_examples/rest_api/post_files_search.rb

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../support/run_rest_example'

data/api_examples/rest_api/put_files_uuid_tags.rb

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../support/run_rest_example'

data/api_examples/support/example_helper.rb

@@ -66,6 +66,21 @@ module ApiExamples::ExampleHelper
     Array(files).each { |file| safe_delete_file(file) }
   end
 
+  def wait_for_file_search(uuid:, timeout: 10, poll_interval: 0.5)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+    loop do
+      matches = client.files.search(query: uuid, limit: 20)
+      return matches if matches.any? { |match| match.uuid == uuid }
+
+      raise "Timed out waiting for file #{uuid} to appear in search" if Process.clock_gettime(
+        Process::CLOCK_MONOTONIC
+      ) >= deadline
+
+      sleep poll_interval
+    end
+  end
+
   def with_fixture_file(name)
     handle = File.open(fixture_path(name), 'rb')
     response = yield handle
@@ -124,7 +139,8 @@ module ApiExamples::ExampleHelper
         size: file.size,
         content_type: 'image/jpeg',
         part_size: multipart_part_size,
-        store: true
+        store: true,
+        tags: %w[example multipart]
       )
     )
     yield file, response

data/api_examples/support/run_rest_example.rb

@@ -12,6 +12,20 @@ module ApiExamples::RunRestExample
         client.project.current
       when 'get_files.rb'
         client.files.list(limit: 2)
+      when 'post_files_search.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          matches = ApiExamples::ExampleHelper.wait_for_file_search(uuid: file.uuid)
+          {
+            'total' => matches.total,
+            'results' => matches.map do |match|
+              {
+                'uuid' => match.uuid,
+                'original_filename' => match.original_filename,
+                'highlight' => match.highlight
+              }
+            end
+          }
+        end
       when 'get_files_uuid.rb'
         ApiExamples::ExampleHelper.with_uploaded_file do |file|
           client.files.find(uuid: file.uuid)
@@ -93,6 +107,22 @@ module ApiExamples::RunRestExample
           client.file_metadata.delete(uuid: file.uuid, key: 'color')
           { 'uuid' => file.uuid, 'key' => 'color', 'deleted' => true }
         end
+      when 'get_files_uuid_tags.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.file_tags.replace(uuid: file.uuid, tags: %w[cat example])
+          client.file_tags.list(uuid: file.uuid)
+        end
+      when 'put_files_uuid_tags.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          change = client.file_tags.replace(uuid: file.uuid, tags: %w[approved example])
+          { 'tags' => change.tags, 'added' => change.added, 'deleted' => change.deleted }
+        end
+      when 'patch_files_uuid_tags.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.file_tags.replace(uuid: file.uuid, tags: %w[draft example])
+          change = client.file_tags.update(uuid: file.uuid, add: ['featured'], delete: ['draft'])
+          { 'tags' => change.tags, 'added' => change.added, 'deleted' => change.deleted }
+        end
       when 'post_addons_aws_rekognition_detect_labels_execute.rb'
         ApiExamples::ExampleHelper.with_uploaded_file do |file|
           client.addons.aws_rekognition_detect_labels(uuid: file.uuid)

data/api_examples/support/run_upload_example.rb

@@ -71,13 +71,19 @@ module ApiExamples::RunUploadExample
 
   def run_base_upload(client)
     ApiExamples::ExampleHelper.with_fixture_file('kitten.jpeg') do |handle|
-      ApiExamples::ExampleHelper.unwrap(client.api.upload.files.direct(file: handle, store: true))
+      ApiExamples::ExampleHelper.unwrap(
+        client.api.upload.files.direct(file: handle, store: true, tags: %w[example base])
+      )
     end
   end
 
   def run_url_upload(client)
     response = ApiExamples::ExampleHelper.unwrap(
-      client.api.upload.files.from_url(source_url: ApiExamples::ExampleHelper::SAMPLE_IMAGE_URL, store: true)
+      client.api.upload.files.from_url(
+        source_url: ApiExamples::ExampleHelper::SAMPLE_IMAGE_URL,
+        store: true,
+        tags: %w[example remote]
+      )
     )
     response
   ensure

data/context7.json

@@ -52,9 +52,11 @@
     "Prefer explicit `Uploadcare::Client` instances for application code, especially when an app uses more than one Uploadcare project.",
     "Configure credentials with `Uploadcare::Client.new(public_key: ..., secret_key: ...)`, `Uploadcare.configure`, or the UPLOADCARE_PUBLIC_KEY and UPLOADCARE_SECRET_KEY environment variables.",
     "Never hardcode real Uploadcare API keys in examples or application code; use environment variables or an application secrets store.",
-    "Use `client.files`, `client.groups`, `client.uploads`, `client.project`, `client.webhooks`, `client.file_metadata`, `client.addons`, and `client.conversions` for normal application workflows.",
+    "Use `client.files`, `client.groups`, `client.uploads`, `client.project`, `client.webhooks`, `client.file_metadata`, `client.file_tags`, `client.addons`, and `client.conversions` for normal application workflows.",
     "Use `client.api.rest` and `client.api.upload` when exact REST API or Upload API endpoint parity is needed.",
     "Use `client.uploads.upload` for automatic upload method selection and `client.uploads.multipart_upload` for explicit multipart uploads.",
+    "Use `client.files.search` for full-text and structured file search; search pagination resends the original POST criteria automatically.",
+    "Pass `tags: [...]` when uploading, and use `client.file_tags` to list, replace, add, or delete tags on an existing file.",
     "Use `MIGRATING_V5.md` when upgrading applications from uploadcare-ruby v4.x to v5."
   ],
   "previousVersions": [

data/docs/release-notes-5.1.0.md

@@ -0,0 +1,33 @@
+# uploadcare-ruby 5.1.0
+
+This release adds file search and file-tag support to the v5 client API. It is backward compatible with 5.0.x and
+does not require an application migration.
+
+## Highlights
+
+- Search files through `client.files.search` using text, UUID, metadata, tag, range, and image filters.
+- Sort search results, inspect match highlights, request `appdata`, and paginate without rebuilding POST criteria.
+- List, replace, add, and delete per-file tags through `client.file_tags`.
+- Assign tags during direct, batch, URL, and multipart uploads.
+- Read tags directly from returned file resources.
+- Use `client.api.rest.files.search` and `client.api.rest.file_tags` for exact REST endpoint access.
+
+## Upgrade Notes
+
+- Requirement: Ruby `>= 3.3`.
+- Update with `bundle update uploadcare-ruby` and run the application's test suite.
+- No configuration or data migration is required from 5.0.x.
+- File search results may be eventually consistent immediately after an upload; retry when a workflow searches for a
+  file it just created.
+- Existing upload calls remain valid. Pass `tags: [...]` only where upload-time tagging is needed.
+- Rollback: pin `uploadcare-ruby` to `5.0.1`.
+
+## Examples
+
+- File search: [`examples/file_search.rb`](../examples/file_search.rb)
+- File tags: [`examples/file_tags.rb`](../examples/file_tags.rb)
+- Raw REST examples: [`api_examples/README.md`](../api_examples/README.md)
+
+## Full Changelog
+
+See [CHANGELOG.md](../CHANGELOG.md).

data/examples/README.md

@@ -29,6 +29,10 @@ mise exec -- ruby examples/simple_upload.rb spec/fixtures/kitten.jpeg
   Force multipart upload and show throughput details.
 - `examples/url_upload.rb`
   Upload a remote URL and show async polling as a follow-up example.
+- `examples/file_search.rb`
+  Search files by text, inspect highlights, and follow the next page.
+- `examples/file_tags.rb`
+  Upload a file with tags, then list, replace, add, and delete tags.
 - `examples/group_creation.rb`
   Upload multiple files, create a group, and print group details.
 

data/examples/file_search.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/uploadcare'
+require 'dotenv/load'
+
+query = ARGV.join(' ')
+
+if query.length < 4
+  puts 'Usage: ruby file_search.rb <query of at least four characters>'
+  puts 'Example: ruby file_search.rb invoice'
+  exit 1
+end
+
+begin
+  client = Uploadcare::Client.new(
+    public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+    secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
+  )
+
+  results = client.files.search(query: query, sort: ['-datetime_uploaded'], limit: 20)
+
+  puts "Found #{results.total} files"
+  results.each do |file|
+    puts [file.uuid, file.original_filename, file.highlight].compact.join(' | ')
+  end
+
+  next_page = results.next_page
+  puts "Next page contains #{next_page.count} files" if next_page
+rescue StandardError => e
+  warn "File search example failed: #{e.message}"
+  exit 1
+end

data/examples/file_tags.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/uploadcare'
+require 'dotenv/load'
+
+file_path = ARGV[0]
+
+unless file_path && File.exist?(file_path)
+  puts 'Usage: ruby file_tags.rb <file_path>'
+  puts 'Example: ruby file_tags.rb photo.jpg'
+  exit 1
+end
+
+begin
+  client = Uploadcare::Client.new(
+    public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+    secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
+  )
+
+  file = File.open(file_path, 'rb') do |io|
+    client.files.upload(io, store: true, tags: %w[example draft])
+  end
+
+  puts "Uploaded #{file.uuid} with tags: #{client.file_tags.list(uuid: file.uuid).join(', ')}"
+
+  change = client.file_tags.replace(uuid: file.uuid, tags: %w[example approved])
+  puts "Replaced tags: #{change.tags.join(', ')}"
+
+  change = client.file_tags.update(uuid: file.uuid, add: ['featured'], delete: ['example'])
+  puts "Updated tags: #{change.tags.join(', ')}"
+rescue StandardError => e
+  warn "File tag example failed: #{e.message}"
+  exit 1
+ensure
+  client.api.rest.files.delete(uuid: file.uuid) if file&.uuid
+end

data/lib/uploadcare/api/rest/file_tags.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+# REST API endpoint for per-file tag operations.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/File-tags
+class Uploadcare::Api::Rest::FileTags
+  # @return [Uploadcare::Api::Rest] Parent REST client
+  attr_reader :rest
+
+  # @param rest [Uploadcare::Api::Rest] Parent REST client
+  def initialize(rest:)
+    @rest = rest
+  end
+
+  # Get the ordered list of tags for a file.
+  #
+  # @param uuid [String] File UUID
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Response containing the `tags` array
+  def list(uuid:, request_options: {})
+    rest.get(path: tags_path(uuid), params: {}, headers: {}, request_options: request_options)
+  end
+  alias index list
+
+  # Replace all tags for a file.
+  #
+  # @param uuid [String] File UUID
+  # @param tags [Array<String>] Complete replacement tag list
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Response containing tags, added, and deleted
+  def replace(uuid:, tags:, request_options: {})
+    rest.put(
+      path: tags_path(uuid), params: { tags: tags }, headers: {}, request_options: request_options
+    )
+  end
+
+  # Atomically add and delete tags for a file.
+  #
+  # Deletions are applied before additions by the API.
+  #
+  # @param uuid [String] File UUID
+  # @param add [Array<String>, nil] Tags to add
+  # @param delete [Array<String>, nil] Tags to delete
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Response containing tags, added, and deleted
+  def update(uuid:, add: nil, delete: nil, request_options: {})
+    params = {}
+    params[:add] = add unless add.nil? || add.empty?
+    params[:delete] = delete unless delete.nil? || delete.empty?
+    body = params.empty? ? {}.to_json : params
+    rest.patch(path: tags_path(uuid), params: body, headers: {}, request_options: request_options)
+  end
+
+  private
+
+  def tags_path(uuid)
+    encoded_uuid = URI.encode_www_form_component(uuid.to_s)
+    "/files/#{encoded_uuid}/tags/"
+  end
+end

data/lib/uploadcare/api/rest/files.rb

@@ -2,11 +2,12 @@
 
 # REST API endpoint for file operations.
 #
-# Provides methods for listing, retrieving, storing, deleting, and copying files.
+# Provides methods for listing, searching, retrieving, storing, deleting, and copying files.
 #
 # @example
 #   rest = Uploadcare::Api::Rest.new(config: config)
 #   rest.files.list(params: { limit: 10 })
+#   rest.files.search(params: { query: "invoice" }, query: { limit: 20 })
 #   rest.files.info(uuid: "file-uuid")
 #
 # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/File
@@ -29,6 +30,22 @@ class Uploadcare::Api::Rest::Files
     rest.get(path: '/files/', params: params, headers: {}, request_options: request_options)
   end
 
+  # Search files by full-text criteria and structured filters.
+  #
+  # Search criteria belong in the JSON request body (`params`). Pagination and
+  # response expansion options belong in the query string (`query`).
+  #
+  # @param params [Hash] Search body (query, phrase, exact, ranges, tags, etc.)
+  # @param query [Hash] Query parameters (limit, offset, include)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Paginated file search results
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/File/operation/searchFiles
+  def search(params: {}, query: {}, request_options: {})
+    rest.post(
+      path: '/files/search/', params: params, query: query, headers: {}, request_options: request_options
+    )
+  end
+
   # Get file information by UUID.
   #
   # @param uuid [String] The file UUID