A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Uploadcare API is how an app or AI agent works with a project's media: uploading a file, storing or deleting it, grouping files together, converting a document or video, and running an add-on like a virus scan. Access is granted through a pair of project keys, a public key that names the project and a secret key used to authenticate management calls, and the keys carry the whole project with no per-method scopes. Uploadcare pins a dated API version requested through a header, and it can push an event to a registered endpoint when a file changes.
How an app or AI agent connects to Uploadcare determines what it can reach. One host handles managing stored files, groups, conversions, and project settings, a separate host handles sending new files in, and Uploadcare can push events back out, with each route governed by the project keys behind it.
The REST API manages existing files, groups, conversions, add-on jobs, webhooks, and project settings at https://api.uploadcare.com. It returns JSON, pages lists with next and previous URLs, requires every path to end in a trailing slash, and pins its version through the Accept header. A call authenticates with the project public and secret keys.
A separate host at https://upload.uploadcare.com accepts new files: a direct base upload for files up to 100 MB, an upload from a public URL, a multipart flow for larger files, and group creation. It authenticates with the public key alone, optionally with a signed expiring token derived from the secret key, so client code can upload without exposing the secret.
Uploadcare POSTs an event payload to an HTTPS endpoint registered through the REST API when a file changes. A subscription is created per event type, can be paused with is_active, and when given a signing_secret each delivery is signed with HMAC-SHA256 so the receiver can verify it came from Uploadcare.
The simple scheme sends the public and secret key together in the Authorization header as Uploadcare.Simple public_key:secret_key. The secret key is included in every request as plain text, so Uploadcare recommends it only for testing, not production. It is rejected over plain HTTP.
The recommended scheme sends Authorization: Uploadcare public_key:signature, where the signature is an HMAC-SHA1 over the request method, an MD5 of the body, the content type, the date, and the path, derived from the secret key without sending it. It also needs a Date header in RFC 2822 GMT, accepted within a 15-minute window of the server's time.
Calls to the separate Upload API authenticate with the project public key, passed as a parameter, and need no secret. Signed uploads can add a signature and an expire timestamp derived from the secret key on a backend, so a client can upload for a limited window without holding the secret.
The Uploadcare API is split into areas an agent can act on, like files, groups, conversions, add-on jobs, webhooks, and project settings. Each area has its own methods, and a write can store, delete, copy, or process real files.
Methods for listing, reading, storing, deleting, and copying files.
Methods for reading and changing a file's metadata key-value pairs.
Methods for creating, listing, reading, and deleting file groups.
Methods on the separate Upload API for sending new files into a project.
Methods for converting documents and videos and polling job status.
Methods for running and polling add-on jobs like virus scan and background removal.
Methods for creating, listing, updating, and removing webhook subscriptions.
Methods for reading project settings.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
FilesMethods for listing, reading, storing, deleting, and copying files.8 | ||||||
| GET | /files/ | List files in the project, paginated by next and previous URLs. | read | — | Current | |
Read-only. Accepts limit (default 100, max 1000), ordering by datetime_uploaded, and a from cursor. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /files/{uuid}/ | Get information about a single file by its UUID, including its metadata and content_info. | read | — | Current | |
Read-only. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /files/{uuid}/storage/ | Store a single file, making it permanently available instead of expiring after 24 hours. | write | — | Current | |
No per-method scope; the project secret key grants this. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook event file.storedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /files/{uuid}/storage/ | Delete a single file from storage by its UUID. | write | — | Current | |
Irreversible removal of the file from storage. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook event file.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /files/storage/ | Store multiple files in one request, up to 100 file UUIDs at a time. | write | — | Current | |
Up to 100 files per request. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook event file.storedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /files/storage/ | Delete multiple files in one request, up to 100 file UUIDs at a time. | write | — | Current | |
Up to 100 files per request; irreversible. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook event file.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /files/local_copy/ | Copy an original file or a modified version of it into the project's default storage. | write | — | Current | |
Produces a new file in default storage. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /files/remote_copy/ | Copy an original file or a modified version of it to a custom remote S3 bucket. | write | — | Current | |
Writes to the project's configured remote storage. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
File metadataMethods for reading and changing a file's metadata key-value pairs.3 | ||||||
| GET | /files/{uuid}/metadata/ | Get all metadata key-value pairs attached to a file. | read | — | Current | |
Read-only. Acts onmetadata Permission (capability)None required VersionIntroduced 2022-09-08 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /files/{uuid}/metadata/{key}/ | Set or update the value of a single metadata key on a file. | write | — | Current | |
Changes the metadata stored on the file. Acts onmetadata Permission (capability)None required VersionIntroduced 2022-09-08 Webhook event file.info_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /files/{uuid}/metadata/{key}/ | Delete a single metadata key from a file. | write | — | Current | |
Removes the named metadata key. Acts onmetadata Permission (capability)None required VersionIntroduced 2022-09-08 Webhook event file.info_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsMethods for creating, listing, reading, and deleting file groups.3 | ||||||
| GET | /groups/ | List file groups in the project, paginated by next and previous URLs. | read | — | Current | |
Read-only. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /groups/{uuid}/ | Get information about a single file group by its ID, which has the form uuid~filecount. | read | — | Current | |
Read-only. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /groups/{uuid}/ | Delete a file group by its ID. The group object is removed but the files in it are left as is. | write | — | Current | |
Removes only the group object, not its files. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Upload APIMethods on the separate Upload API for sending new files into a project.5 | ||||||
| POST | /base/ | Upload a new file directly, up to 100 MB, on the Upload API host upload.uploadcare.com. | write | — | Current | |
Upload API; authenticates with the public key, not the secret key. Files over 100 MB use multipart. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook event file.uploadedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /from_url/ | Fetch a file from a public URL into the project; returns a token to poll for upload status. | write | — | Current | |
Upload API; asynchronous, poll /from_url/status/ with the returned token. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook event file.uploadedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /multipart/start/ | Begin a multipart upload for a large file; returns presigned URLs for each part. | write | — | Current | |
Upload API; each part except the last is at least 5 MiB. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /multipart/complete/ | Finish a multipart upload once all parts are uploaded, producing the final file. | write | — | Current | |
Upload API; called after all parts are uploaded. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook event file.uploadedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /group/ | Create a file group from a set of uploaded file UUIDs on the Upload API. | write | — | Current | |
Upload API; groups are created here, then read and deleted on the REST API. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConversionMethods for converting documents and videos and polling job status.5 | ||||||
| POST | /convert/document/ | Convert a document to another format, optionally saving multi-page output as a group; returns a job token. | write | — | Current | |
Asynchronous; poll the returned token. save_in_group outputs a group of files. Acts onconversion_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /convert/document/{uuid}/ | Read a document's format and the conversion formats available for it before starting a job. | read | — | Current | |
Read-only. Acts onconversion_job Permission (capability)None required VersionIntroduced 2023-11-07 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /convert/document/status/{token}/ | Get the status and result of a document conversion job by its token. | read | — | Current | |
Read-only; poll until the job is finished or failed. Acts onconversion_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /convert/video/ | Convert a video's quality, format, and size, cut it, and generate thumbnails; returns a job token. | write | — | Current | |
Asynchronous; poll the returned token. Outputs mp4, webm, or ogg. Acts onconversion_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /convert/video/status/{token}/ | Get the status and result of a video conversion job by its token. | read | — | Current | |
Read-only; poll until the job is finished or failed. Acts onconversion_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Add-onsMethods for running and polling add-on jobs like virus scan and background removal.6 | ||||||
| POST | /addons/uc_clamav_virus_scan/execute/ | Run the ClamAV virus scan add-on on a file; returns a request_id to poll. | write | — | Current | |
Asynchronous; an infected file fires the file.infected webhook. Acts onaddon_job Permission (capability)None required VersionAvailable since the API’s base version Webhook event file.infectedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /addons/uc_clamav_virus_scan/execute/status/ | Get the status of a ClamAV virus scan job by its request_id. | read | — | Current | |
Read-only; request_id passed as a query parameter. Acts onaddon_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /addons/remove_bg/execute/ | Run the Remove.bg background removal add-on on an image; returns a request_id to poll. | write | — | Current | |
Asynchronous; produces a new file with the background removed. Acts onaddon_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /addons/remove_bg/execute/status/ | Get the status of a Remove.bg background removal job by its request_id. | read | — | Current | |
Read-only; request_id passed as a query parameter. Acts onaddon_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /addons/aws_rekognition_detect_labels/execute/ | Run AWS Rekognition label detection on an image; returns a request_id to poll. | write | — | Current | |
Asynchronous; stores detected labels as appdata on the file. Acts onaddon_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /addons/aws_rekognition_detect_labels/execute/status/ | Get the status of an AWS Rekognition label detection job by its request_id. | read | — | Current | |
Read-only; request_id passed as a query parameter. Acts onaddon_job Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for creating, listing, updating, and removing webhook subscriptions.4 | ||||||
| POST | /webhooks/ | Create a webhook subscription for one event type, with an optional signing secret. | write | — | Current | |
target_url and event are required; signing_secret enables HMAC-SHA256 signatures. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /webhooks/ | List the project's webhook subscriptions. | read | — | Current | |
Read-only. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /webhooks/{id}/ | Update a webhook's attributes, such as its target URL, event, or active state. | write | — | Current | |
Changes where and whether events are delivered. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /webhooks/unsubscribe/ | Unsubscribe and delete a webhook, identified by its target_url. | write | — | Current | |
target_url in the request body identifies which webhook to remove. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectMethods for reading project settings.1 | ||||||
| GET | /project/ | Get information about the account project, such as its name, public key, and collaborators. | read | — | Current | |
Read-only. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Uploadcare can notify an app when something happens to a file, like a file being uploaded, stored, deleted, or found to be infected. It POSTs an event payload describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
file.uploaded | A new file finished uploading to the project. | In-app only |
file.infected | A file was found to be infected by the ClamAV virus scan add-on. | /addons/uc_clamav_virus_scan/execute/ |
file.stored | A file was stored, making it permanently available rather than expiring as a temporary upload. | /files/{uuid}/storage//files/storage/ |
file.deleted | A file was deleted from storage. | /files/{uuid}/storage//files/storage/ |
file.info_updated | A file's information changed, for example its metadata was updated. | In-app only |
Uploadcare meters how fast an app can call the REST API and returns a throttled response when a project sends requests too quickly, and it caps how many files a single batch or list call can carry.
Uploadcare meters REST API requests per project and returns HTTP 429 with a detail of 'Request was throttled' when a project calls too quickly; a client should back off and retry. The reference does not publish a fixed per-second number for the REST API, so a real integration should treat the limit as discoverable and handle 429 rather than assume a ceiling. Conversion and add-on work is asynchronous: the call that starts a job returns immediately with a token or request_id, and the job runs in the background while the integration polls a status method.
List methods are cursor-based. A files or groups list returns next and previous URLs to walk pages, and the files list accepts limit, ordering by datetime_uploaded ascending or descending, and a from cursor. An integration follows the next URL until it is absent rather than computing page offsets.
The files list returns up to 100 files per page by default and 1000 at most via limit. Batch store and batch delete each accept up to 100 file UUIDs per request. The Upload API base endpoint takes files up to 100 MB in a single request; larger files must use multipart upload, where each part except the last is at least 5 MiB.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request was malformed, or Uploadcare.Simple authentication was attempted over plain HTTP instead of HTTPS. | Send the request over HTTPS, check the body and parameters against the method, and confirm the trailing slash on the path. |
| 401 | unauthorized | Authentication failed, with a detail such as 'Incorrect authentication credentials' or 'Invalid signature'. | Check the public and secret keys, and for the signature scheme recompute the HMAC and confirm the Date header is within the 15-minute window. |
| 403 | forbidden | The credentials are valid but not allowed to perform the request. | Confirm the keys belong to the project that owns the file or resource being acted on. |
| 404 | not_found | The requested file, group, or resource does not exist in this project. | Verify the UUID and that the resource lives in the project the keys belong to. |
| 406 | not_acceptable | The Accept header named an unsupported or missing API version. | Set Accept to application/vnd.uploadcare-v0.7+json or another supported version. |
| 429 | throttled | Too many requests arrived too quickly for the project; the detail field reads 'Request was throttled'. | Back off and retry with exponential backoff, and smooth the request rate. |
Uploadcare pins one dated REST API version, requested through the Accept header, and keeps a backward-compatible version supported for at least two years after the next major one ships.
Version 0.7 is the current REST API version, pinned through the Accept header as application/vnd.uploadcare-v0.7+json. It restructured file information and added the add-on framework, and has since gained file metadata, new webhook events, and document conversion.
Added a method to determine a document's format and the conversion options available for it before starting a job.
Document conversion gained the ability to split a multi-page document into a group of files.
Webhook payloads gained an initiator field and three new event types were added.
Introduced file metadata, a set of arbitrary key-value pairs attached to a file, with methods to read and change it.
Pin v0.7 through the Accept header and move up only when a new major version ships.
Uploadcare REST API changelog ↗Bollard AI sits between a team's AI agents and Uploadcare. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.