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

# Managing uploaded files

> Organize your files further by tagging them, create new file versions, make a decision based on file info, run heavy tasks in the background.

Alongside [upload functionality](/docs/uploading-files/), Uploadcare provides
additional methods for managing already uploaded files with its REST API.
Organize your files further by tagging them, creating new file versions,
making decisions based on file info, and running heavy tasks in the background.

Our [REST API](https://uploadcare.com/docs/api/rest/) is documented in the OpenAPI 3 format. We'll provide
links to the respective operations along this guide.

## CRUD

Basic building blocks of our API:

* C: upload, create, copy
* R: list files, get file info
* U: store, add arbitrary and processing metadata
* D: delete

Here is a basic example of a CRUD operation: retrieving the list of files.

#### cURL

```bash
curl "https://api.uploadcare.com/files/" \
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
     -H "Authorization: Uploadcare.Simple UPLOADCARE_PUBLIC_KEY:UPLOADCARE_SECRET_KEY"
```

#### JavaScript

```js
import { listOfFiles, paginate } from '@uploadcare/rest-client'

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY'
})

const paginatedListOfFiles = paginate(listOfFiles)
const pages = paginatedListOfFiles(
  {},
  { authSchema: uploadcareSimpleAuthSchema }
)

for await (const page of pages) {
  for (const file of page.results) {
    console.log(`URL: ${file.url}`)
  }
}
```

#### PHP

```php
<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);

$api = (new Uploadcare\Api($configuration))->file();
$list = $api->listFiles();
foreach ($list->getResults() as $result) {
    echo \sprintf('URL: %s', $result->getUrl());
}
while (($next = $api->nextPage($list)) !== null) {
    foreach ($next->getResults() as $result) {
        echo \sprintf('URL: %s', $result->getUrl());
    }
}
```

#### Python

```python
from pyuploadcare import Uploadcare
uploadcare = Uploadcare(public_key='YOUR_PUBLIC_KEY', secret_key='YOUR_SECRET_KEY')

files = uploadcare.list_files(stored=True, limit=10)
for file in files:
    print(file.info)
```

#### Ruby

```ruby
require 'uploadcare'
Uploadcare.config.public_key = "YOUR_PUBLIC_KEY"
Uploadcare.config.secret_key = "YOUR_SECRET_KEY"

list = Uploadcare::FileList.file_list(stored: true, removed: false, limit: 100)
list.each { |file| puts file.inspect }
```

#### Swift

```swift
import Uploadcare

let uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")

let query = PaginationQuery()
  .stored(true)
  .ordering(.dateTimeUploadedDESC)
  .limit(10)
var list = uploadcare.listOfFiles()

try await list.get(withQuery: query)
print(list)
```

#### Kotlin

```kotlin
import com.uploadcare.android.library.api.UploadcareClient

val uploadcare = UploadcareClient(publicKey = "YOUR_PUBLIC_KEY", secretKey = "YOUR_SECRET_KEY")

val filesQueryBuilder = uploadcare.getFiles()
val files = filesQueryBuilder
    .stored(true)
    .ordering(Order.UPLOAD_TIME_DESC)
    .asList()
Log.d("TAG", files.toString())
```

You can learn about [uploading files](/docs/uploading-files/) in the respective
article. Everything else is down below.

## Get file info

| Operation                                                             | Path                  |
| --------------------------------------------------------------------- | --------------------- |
| [List of files](https://uploadcare.com/docs/api/rest/file/files-list) | `GET /files/`         |
| [File info](https://uploadcare.com/docs/api/rest/file/info)           | `GET /files/{uuid}`   |
| [Search files](https://uploadcare.com/docs/api/rest/file/file-search) | `POST /files/search/` |

You can list files in your project and get their info. File info provides you
with insights into the content of the file. Based on the file information, you
can decide to keep or delete it, create a modified copy, add metadata, or
process it in other ways. Read down below about these features.

To find files, use the search endpoint. Use `query` for a quick full-text search across filename,
metadata, and MIME type. Use `phrase` to search specific fields, or combine `exact`,
`datetime_uploaded`, `size`, `is_image`, and `tags` for structured filtering. Note that newly
uploaded files may not appear in search results immediately. Read more about [file search](/docs/file-search/).

## Keep or remove files

| Operation                                                                     | Path                            |
| ----------------------------------------------------------------------------- | ------------------------------- |
| [Store file](https://uploadcare.com/docs/api/rest/file/store-file)            | `PUT /files/{uuid}/storage/`    |
| [Batch file storing](https://uploadcare.com/docs/api/rest/file/files-storing) | `PUT /files/storage/`           |
| [Delete file](https://uploadcare.com/docs/api/rest/file/delete-file-storage)  | `DELETE /files/{uuid}/storage/` |
| [Batch file delete](https://uploadcare.com/docs/api/rest/file/files-delete)   | `DELETE /files/storage/`        |

If you haven't [stored the file during uploading](/docs/uploading-files/#file-storing-behavior), you can
store it afterwards to keep it from being removed after 24 hours. This might be
the case if you look into file info before making a decision. This operation is
possible for up to 100 files in one go.

You can also delete files anytime, also up to 100 in one go. Deleting a file automatically invalidates its cached versions across the CDN, see [cache duration](/docs/delivery/cdn/#cache-duration) for details.

Files are immutable, but you can make their [local copies](#copy) to create new
file versions.

As for changing the file name, you can apply any name when
[delivering](/docs/cdn-operations/#cdn-filename) it.

## Catch file events with webhooks

| Operation                                                                      | Path                           |
| ------------------------------------------------------------------------------ | ------------------------------ |
| [List of webhooks](https://uploadcare.com/docs/api/rest/webhook/webhooks-list) | `GET /webhooks/`               |
| [Create webhook](https://uploadcare.com/docs/api/rest/webhook/create)          | `POST /webhooks/`              |
| [Update webhook](https://uploadcare.com/docs/api/rest/webhook/update-webhook)  | `PUT /webhooks/{id}`           |
| [Delete webhook](https://uploadcare.com/docs/api/rest/webhook/unsubscribe)     | `DELETE /webhooks/unsubscribe` |

Uploadcare can notify your application about certain events with webhooks. For
example, you may need to add or update a record in your database when a new
file has been uploaded, or copy it to the remote storage if it qualifies your
criteria. Read more about [webhooks](/docs/webhooks/).

## Copy locally and remotely \[#copy]

| Operation                                                                                   | Path                       |
| ------------------------------------------------------------------------------------------- | -------------------------- |
| [Copy file to local storage](https://uploadcare.com/docs/api/rest/file/create-local-copy)   | `POST /files/local_copy/`  |
| [Copy file to remote storage](https://uploadcare.com/docs/api/rest/file/create-remote-copy) | `POST /files/remote_copy/` |

### Copying large files

Large file copying via `POST /files/local_copy/` is limited.

For `POST /files/local_copy/`, if the source CDN URL includes image processing operations, the file size must not exceed **100 MB**.

For full details and possible error responses, see the API reference:

* [Copy file to local storage](https://uploadcare.com/docs/api/rest/file/create-local-copy)
* [Copy file to remote storage](https://uploadcare.com/docs/api/rest/file/create-remote-copy)

A local copy is used when you want to create a version of the current file. For
example, when you need to ["bake in"](/docs/mutability/#copy) changes to the image you
made. Or when you receive a big video file and want to [encode](#process) it
in an efficient format and smaller size.

Remote copy is helpful when you need to manually copy selected files to your
[S3 bucket](/docs/s3-integration/) to establish a specific file workflow.

## Add arbitrary metadata \[#metadata]

| Operation                                                                                                  | Path                                   |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| [Get file's metadata](https://uploadcare.com/docs/api/rest/file-metadata/file-metadata)                    | `GET /files/{uuid}/metadata/`          |
| [Get metadata key's value](https://uploadcare.com/docs/api/rest/file-metadata/key)                         | `GET /files/{uuid}/metadata/{key}/`    |
| [Update metadata key's value](https://uploadcare.com/docs/api/rest/file-metadata/update-file-metadata-key) | `PUT /files/{uuid}/metadata/{key}/`    |
| [Delete metadata key](https://uploadcare.com/docs/api/rest/file-metadata/delete-file-metadata-key)         | `DELETE /files/{uuid}/metadata/{key}/` |

You can add additional, arbitrary key-value data associated with uploaded
files. For example, you could store user IDs, order IDs, or tags. This is
available both [during](/docs/uploading-files/#metadata) and after. Read more about
[arbitrary file metadata](/docs/file-metadata/).

## Add tags \[#tags]

| Operation                                                                 | Path                        |
| ------------------------------------------------------------------------- | --------------------------- |
| [Get tags](https://uploadcare.com/docs/api/rest/file/get-tags)            | `GET /files/{uuid}/tags/`   |
| [Replace tags](https://uploadcare.com/docs/api/rest/file/put-tags)        | `PUT /files/{uuid}/tags/`   |
| [Add / remove tags](https://uploadcare.com/docs/api/rest/file/patch-tags) | `PATCH /files/{uuid}/tags/` |

Each file can carry an ordered list of string tags. Tags are available at
upload time and can be managed via the REST API afterwards. They appear in all
file info responses and can be used as a filter in [file search](/docs/file-search/).
Read more about [file tags](/docs/file-tags/).

## Async processing \[#process]

| Type of operation                                                                   | Path                                          |
| ----------------------------------------------------------------------------------- | --------------------------------------------- |
| [Conversion](https://uploadcare.com/docs/api/rest/conversion/document-convert-info) | `POST` conversion operation, `GET` job status |
| [Add-ons](https://uploadcare.com/docs/api/rest/add-ons/aws-rekognition-execute)     | `POST` execute add-on, `GET` execution status |

We have articles about each of these operations:

* [Background removal](/docs/remove-bg/)
* [Object recognition](/docs/object-recognition/)
* [Video processing](/docs/transformations/video-encoding/)
* [Document conversion](/docs/transformations/file-conversion/)
* [Unsafe content moderation](/docs/unsafe-content/)
* [Virus checking on request](/docs/security/malware-protection/)

## API integrations

You don't have to code most of the low-level API interactions. We have
high-level libraries for all popular platforms:

* [JavaScript](/docs/integrations/javascript/)
* [PHP](/docs/integrations/php/)
* [Python & Django](/docs/integrations/python/)
* [Ruby](/docs/integrations/ruby/) and [Rails](/docs/integrations/rails/)
* [Swift](/docs/integrations/swift/) (iOS, iPadOS, macOS, tvOS, Linux)
* [Kotlin](/docs/integrations/android/) (Android)
* [Java](/docs/integrations/java/)
* [Golang](/docs/integrations/golang/)
* [Rust](/docs/integrations/rust/)

## Uploadcare Dashboard

API methods mentioned above run our Dashboard [files section](https://app.uploadcare.com/projects/-/files/), where you can view
your files and perform such operations.

You can easily build your own dashboards. We have a few examples of how it can be
done:

* [https://github.com/uploadcare/uploadcare-php-example](https://github.com/uploadcare/uploadcare-php-example)
* [https://github.com/uploadcare/pyuploadcare-example](https://github.com/uploadcare/pyuploadcare-example)
* [https://github.com/uploadcare/uploadcare-rails-example](https://github.com/uploadcare/uploadcare-rails-example)
* [https://github.com/uploadcare/uploadcare-swift/tree/master/Demo](https://github.com/uploadcare/uploadcare-swift/tree/master/Demo)
* [https://github.com/uploadcare/uploadcare-android/tree/master/example](https://github.com/uploadcare/uploadcare-android/tree/master/example)

## Analyze project usage

View your project [analytics](https://app.uploadcare.com/projects/-/analytics/) for the chosen period:

* Operations
* Uploads
* Storage
* Traffic

You can view detailed usage statistics for the following categories:

* Popular files
* Operations
* CDN traffic
* Storage
* Uploads
* API requests
* API errors breakdown

## Debug with API logs

Detailed [API logs](https://app.uploadcare.com/projects/-/api-logs/) are helpful for debugging purposes.