Menu

Mattering Automations Uploadcare integration

Connect Uploadcare to Mattering Automations: upload from a URL, store files before their 24-hour clock runs out, tag and search them, manage groups and metadata, subscribe webhooks, convert documents and video, and run the four Add-Ons as workflow steps, authenticated with one project key pair under Uploadcare's signed scheme.

The Mattering Automations Uploadcare integration puts Uploadcare REST API version 0.7 and the Upload API on your automation canvas: fetch a file server-side from a URL, poll it into existence, store it permanently, read and search files, attach metadata and tags, build groups, subscribe webhooks, queue document and video conversions, and run the four Add-Ons for virus scanning, label detection, content moderation and background removal.

The credential has two fields and both come from the project's API keys page in the Uploadcare dashboard: a public key, which identifies the project, and a secret key, which is never sent anywhere. Uploadcare documents two authorization schemes and only one of them is for production, so this integration implements only the signed Uploadcare scheme: the request carries the public key alongside a signature computed over the verb, the body digest, the content type, a fresh timestamp and the full request URI. The Uploadcare.Simple scheme puts the secret key in cleartext in every request and the vendor itself does not recommend it in production, so it is deliberately not offered here. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.

One behaviour is worth understanding before your first workflow, because it is the most common way an Uploadcare automation fails and it fails without an error. Every file arrives TEMPORARY and Uploadcare deletes it within 24 hours unless it is stored, or unless the project has Auto file storing switched on. An automation that uploads and never stores loses everything it collected the next day, having received a success on every call it made. Uploadcare: Get Project reports whether that setting is on, and Uploadcare: Store File is the call that makes a file permanent.

Before you start

  • An Uploadcare account with a project you can read API keys from. Both the public key and the secret key are on the project's API keys page in the dashboard.
  • A decision about storage, made before the first run. Check Uploadcare: Get Project for whether Auto file storing is enabled. If it is not, every workflow that uploads must also store, or the files are deleted within 24 hours.
  • A publicly reachable URL to ingest from. Uploadcare fetches URLs server-side, and this integration deliberately ships no direct byte upload, because a canvas field cannot hold file content.
  • For the Add-Ons and for remote copy, a plan and a project configured for them. ClamAV virus scanning, AWS Rekognition label detection and moderation, and remove.bg background removal are third-party services billed through Uploadcare, and copying to custom storage writes into an S3 bucket that has to be connected to the project first. Confirm what your plan includes on Uploadcare's pricing pages before designing a workflow around those nine nodes.
  • A Mattering workspace with access to the Automations app.
  • Not required and not stored here: any project identifier. The key pair is scoped to one project, which is why no node asks which project to use.

Get an Uploadcare key pair

Uploadcare issues keys per project rather than per account, so the first decision is which project this credential should reach. The public key identifies that project and is also the Upload plane's entire authentication as a request parameter. The secret key never leaves Mattering: it is the HMAC key used to sign each REST request and, on projects with Signed Uploads enabled, each upload.

Sign in to the Uploadcare dashboard and select the project this credential should reach.
Open the project's API keys page and copy the Public key and the Secret key.
The secret key addresses everything in that project, including the four destructive nodes. If production and experiments share one Uploadcare project, consider separating them into two projects and connecting a credential for each, so an automation pointed at the wrong file cannot reach production data at all.
You do not need a project id, a region or a base URL. The key pair already selects the project, and both planes are addressed automatically from the node you choose.

Connect Uploadcare to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Uploadcare from the list.
Click Create new credential, paste the public key into Public Key and the secret key into Secret Key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs. The secret key is used only to compute signatures; it is never sent to Uploadcare.
Click Test Connection. Mattering signs a read of the project endpoint, which is the cheapest authenticated call in the API: no path parameters, no query string, no pagination, and a small object naming the project. A pass proves the key pair is live and belongs to one project, and that the signature construction, the timestamp format and the pinned version header are all correct together.
The probe covers the REST plane only. The Upload plane is a different host with different authentication and a different signature algorithm, so a project with Signed Uploads enabled is not exercised until you actually run Uploadcare: Upload File from URL. Do that once before trusting that half.
Click Connect. All 41 Uploadcare nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: an Uploadcare section should list the read and action nodes. Drop Uploadcare: Get Project onto the canvas and run a test step. It is the integration's natural probe, and it answers the one question that changes how you build everything else: read autostore_enabled in the response. If it is false, every workflow that uploads must also store, or the files are gone within 24 hours.

Then run Uploadcare: List Files and read a row. You get each file's UUID, original filename, MIME type, size, CDN URL, storage timestamps, metadata, tags and content details, and the response carries next and previous URLs plus totals for stored, unstored and removed. Two shapes to notice while you are here, because they are not the same across this API: the file list wraps its rows in a results array, while Uploadcare: List Webhooks answers with a BARE ARRAY, so its paths read data[0].id rather than data.results[0].id. Everything in this verify path is read-only, so it cannot reach the four destructive nodes and is safe to re-run whenever you rotate the secret key.

Node reference

41 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 19

Uploadcare: Get Background Removal Status

uploadcare_get_remove_background_status

Check a remove.bg Add-On run. Poll until data.status is done or error. Unlike the other three Add-On status nodes this one returns a payload worth reading: data.result.file_id is the UUID of the NEW background-free image, which is what a following node should act on.

Uploadcare: Get Content Moderation Status

uploadcare_get_moderation_status

Check an AWS Rekognition moderation run. Poll until data.status is done or error. The moderation labels are in the file's appdata rather than in this response: read them with Uploadcare: Get File using include appdata.

Uploadcare: Get Document Conversion Info

uploadcare_get_document_info

Find out what a document actually is and what it can be converted into, before spending a conversion job on it. Returns the detected source format, the list of target formats available for it, and any conversion groups already produced from it. data.error is non-null when Uploadcare cannot handle the file at all.

Uploadcare: Get Document Conversion Status

uploadcare_get_document_convert_status

Check one document conversion job by its token. data.status moves through pending and processing to finished, failed or canceled; data.error carries the reason on failure and data.result repeats the output, including the converted file's UUID. Poll this rather than assuming a queued conversion has landed.

Uploadcare: Get File

uploadcare_get_file

Get one file's full record by UUID: filename, MIME type, size, CDN URL, whether it is stored, and the content_info block with image dimensions, colour mode, EXIF and video codec details. Poll data.is_ready after an upload before using the file, and read data.datetime_stored to tell a permanent file from one that expires within 24 hours.

Uploadcare: Get File Metadata

uploadcare_get_file_metadata

Get every metadata key and value on a file as a flat object. Metadata is arbitrary data attached at upload time or afterwards, typically an id from your own system. Downstream paths read straight through, for example data.order_id. Metadata is supplied by whoever uploaded the file, so escape it before putting it in HTML or a SQL parameter.

Uploadcare: Get File Tags

uploadcare_get_file_tags

Get a file's ordered tag list. Tags are short normalized labels set at upload or through the tag nodes here, and they are usable as a filter in Uploadcare: Search Files. Returns an empty array when the file has none.

Uploadcare: Get Group

uploadcare_get_group

Get one group by id, including the list of files inside it. The files array can contain nulls where a member file has since been deleted, so guard against that before iterating. Group ids are a UUID, a tilde, and the file count.

Uploadcare: Get Label Detection Status

uploadcare_get_detect_labels_status

Check an AWS Rekognition label-detection run. Poll until data.status is done or error. The labels themselves are in the file's appdata, not in this response: read them with Uploadcare: Get File using include appdata.

Uploadcare: Get Metadata Key

uploadcare_get_metadata_key

Read one metadata value from a file. The response body is a bare JSON string rather than an object, so the value arrives as data itself, not data.something. Run this before Delete Metadata Key if the workflow needs to be able to put the value back.

Uploadcare: Get Project

uploadcare_get_project

Get the project the credential belongs to: its name, public key, collaborators, and whether Auto file storing is on. That last flag is the one worth reading in a workflow, because it decides what happens to an upload that does not set store explicitly: with autostore off, the file is deleted within 24 hours. No parameters, so this is also the connector's auth probe.

Uploadcare: Get Upload Status

uploadcare_get_upload_status

Turn an upload token from Uploadcare: Upload File from URL into a result. data.status moves waiting, progress, then either success - where the response widens into the full file info including data.uuid - or error, where data.error says why. Poll this until one of those two; the UUID does not exist before it. Runs against upload.uploadcare.com.

Uploadcare: Get Uploaded File Info

uploadcare_get_uploaded_file_info

Read a file's record from the UPLOAD API rather than the REST API. Useful immediately after an upload, because it needs only the public key and reports is_ready and is_stored directly. Note the older field shape: image_info and video_info here, where the REST plane's Uploadcare: Get File returns content_info. Prefer the REST node for anything downstream that also reads tags or appdata.

Uploadcare: Get Video Conversion Status

uploadcare_get_video_convert_status

Check one video encoding job by its token. data.status moves through pending and processing to finished, failed or canceled; data.error carries the reason on failure and data.result holds the encoded file's UUID plus the thumbnails group id. Video encoding is slow, so poll this rather than sleeping a fixed interval.

Uploadcare: Get Virus Scan Status

uploadcare_get_virus_scan_status

Check a ClamAV Add-On run. Poll until data.status is done or error; in_progress means keep waiting. The verdict itself is not in this response - once the status is done, read the file with Uploadcare: Get File using include appdata and look at appdata.uc_clamav_virus_scan.data.infected.

Uploadcare: List Files

uploadcare_list_files

List the project's files, newest or oldest first, with each file's UUID, original filename, MIME type, size, CDN URL, storage timestamps, metadata, tags and content details. This is the node every other Uploadcare node leans on: it is the source for every file picker in this connector and the cheapest way to confirm a credential works. The response also carries totals for stored, unstored and removed files. Paging is cursor-based: follow data.next rather than incrementing an offset.

Uploadcare: List Groups

uploadcare_list_groups

List the project's file groups, each with its id, creation time, file count, CDN URL and API URL. A group bundles already-uploaded files so they can be addressed together, for example everything a user submitted in one form. This is the source for every group picker in this connector. Paging is cursor-based: follow data.next.

Uploadcare: List Webhooks

uploadcare_list_webhooks

List the project's webhook subscriptions with their id, event, target URL, active flag, payload version and signing secret. Note the response is a BARE ARRAY, so paths are data[].id rather than data.results[].id. This is the source for the webhook pickers in this connector.

Uploadcare: Search Files

uploadcare_search_files

Search the project's files by filename, metadata, MIME type, UUID or tags, with optional filtering on size, upload date and whether the file is an image. It is a POST because the query is a structured object, but it reads and changes nothing. At least one condition is required. All top-level conditions are ANDed; the only OR is inside a single exact field, inside query, or in tags.any, and the only NOT is tags.none or is_image false. Newly uploaded files are indexed asynchronously and may not appear immediately.

Action nodes 22

Uploadcare: Convert Document

uploadcare_convert_document

Queue document conversions, for example DOCX to PDF or PDF pages to JPEG. Each entry in paths is a source UUID followed by the /document/ operator and the target format. Conversion is asynchronous: the response returns a token per accepted path for Uploadcare: Get Document Conversion Status, plus a problems map naming any path it rejected. The source file is never modified; each conversion creates a new file.

Uploadcare: Convert Video

uploadcare_convert_video

Queue video encoding jobs: change format to mp4, webm or ogg, adjust quality and size, cut a segment, and generate thumbnails. Each entry in paths is a source UUID followed by the /video/ operator and any options. Asynchronous: the response returns a token per accepted path for Uploadcare: Get Video Conversion Status, along with the thumbnails group id. The source file is never modified.

Uploadcare: Copy File to Custom Storage

uploadcare_copy_file_remote

Copy a file, or a transformed version of it, out to an S3 bucket connected to the project as a custom storage. Returns an s3:// URL. Source files may be stored or merely uploaded but must not be deleted, and must not exceed 5 GB. HTTP 201 means the copy was written; HTTP 200 means a file with that name ALREADY EXISTED at the destination and nothing was overwritten, which is the response to check when a scheduled copy appears to succeed but the bucket never changes.

Uploadcare: Copy File to Uploadcare Storage

uploadcare_copy_file_local

Copy a file, or a TRANSFORMED version of it, into the project's own storage as a new file with a new UUID. This is how a CDN transformation becomes a stored asset: pass a CDN path carrying operators as the source and the rendered result is what gets saved. The source may be stored or merely uploaded but must not be deleted. Size ceilings are 100 MB when the source URL carries transformation operators and 5 GB when it does not. The immediate 201 can report size 0 and application/octet-stream while the copy finishes; read the new UUID back with Uploadcare: Get File for the settled values.

Uploadcare: Create Group

uploadcare_create_group

Bundle already-uploaded files into a group so they can be addressed with one id and one CDN URL. Groups are IMMUTABLE: there is no add-to-group or remove-from-group call anywhere in the API, so changing the contents means creating a new group with a new id. Every file must belong to the same project as the group. Grouping does not store the files, so temporary members still expire on their own 24-hour clock. Runs against upload.uploadcare.com with the public key.

Uploadcare: Create Webhook

uploadcare_create_webhook

Subscribe a URL to an Uploadcare event so the project posts a notification when it happens. The target URL must be unique for each project and event-type pair, so the same receiver can serve several events but not the same event twice. Set a signing secret and Uploadcare signs each payload with HMAC-SHA256 in the X-Uc-Signature header as v1=<hex digest>, which is what lets the receiver reject forged calls. Request body is form-encoded, not JSON.

Uploadcare: Delete File

uploadcare_delete_file

PERMANENTLY delete one file. The path says storage and the verb reads like the inverse of storing, but it is not: v0.7 retired DELETE /files/{uuid}/ and this endpoint took its place. It sets datetime_removed, nulls original_file_url, and there is NO restore endpoint anywhere in the API. The file's metadata row survives and stays visible through List Files with removed true, which is not the same as being recoverable. Uploadcare also states that this does not invalidate the CDN cache, so a deleted file can keep being served from an edge to anyone holding its URL.

Uploadcare: Delete Files (Bulk)

uploadcare_delete_files_bulk

PERMANENTLY delete up to 100 files in one call. Same irreversibility as Uploadcare: Delete File, multiplied: there is no restore endpoint, and the CDN cache is not invalidated. The response splits into result (the deleted records) and problems (UUIDs that could not be deleted). A partial failure still returns HTTP 200.

Uploadcare: Delete Group

uploadcare_delete_group

Delete a group object. THE FILES IN THE GROUP ARE LEFT INTACT: this removes only the grouping, not any content. It is still destructive because there is no restore endpoint and groups are immutable, so the recovery path is creating a NEW group from the same files, which mints a NEW id. Every stored group id and every group CDN URL pointing at the old one stops resolving. Returns HTTP 204 with no body.

Uploadcare: Delete Metadata Key

uploadcare_delete_metadata_key

Remove one metadata key from a file. Returns HTTP 204 with no body. This is classed as a reversible write rather than a destructive one on purpose: it touches no file bytes, Uploadcare keeps no metadata history, and the exact value can be read beforehand with Uploadcare: Get Metadata Key and put back with one Update Metadata Key call.

Uploadcare: Delete Webhook

uploadcare_delete_webhook

Unsubscribe and delete a webhook. It is keyed by TARGET URL and nothing else, while a target URL is only required to be unique per project and EVENT TYPE, so one call can remove several subscriptions that share a receiver across different events. Returns HTTP 204 with no body, which is the same answer whether one subscription went or three did. There is no undo: the subscription and any auto-generated signing secret are gone, and event delivery stops silently. To pause deliveries reversibly, set is_active false with Uploadcare: Update Webhook instead.

Uploadcare: Execute Background Removal

uploadcare_execute_remove_background

Run the remove.bg Add-On to strip the background from an image. Execution is asynchronous: this returns a request id, and Uploadcare: Get Background Removal Status returns the NEW file's id once it is done. The source image is not modified or replaced; a separate file is produced.

Uploadcare: Execute Content Moderation

uploadcare_execute_moderation

Run the AWS Rekognition moderation Add-On against an image to detect unsafe content. Execution is asynchronous: this returns a request id for Uploadcare: Get Content Moderation Status. Moderation labels land in the file's appdata under aws_rekognition_detect_moderation_labels, each with a confidence score and a parent category such as Violence. This node flags content; it never deletes anything.

Uploadcare: Execute Label Detection

uploadcare_execute_detect_labels

Run the AWS Rekognition label-detection Add-On against an image to tag what is in it. Execution is asynchronous: this returns a request id for Uploadcare: Get Label Detection Status. The detected labels are written into the file's appdata under aws_rekognition_detect_labels, each with a confidence score and parent categories, and are read back with Get File using include appdata.

Uploadcare: Execute Virus Scan

uploadcare_execute_virus_scan

Run the ClamAV Add-On against a file. Execution is asynchronous: this returns a request id, and Uploadcare: Get Virus Scan Status turns that into a verdict. The result lands in the file's appdata under uc_clamav_virus_scan with an infected flag and, when positive, infected_with. WARNING: setting params to {"purge_infected": true} makes this node PERMANENTLY DELETE the file when the scan finds an infection. The flag is off by default and is the only way a node not marked destructive can destroy a file here.

Uploadcare: Replace File Tags

uploadcare_replace_file_tags

Replace a file's ENTIRE tag set. Any tag not in the new list is removed, and an empty array clears every tag. It is still a reversible write: the response returns the exact deleted list, so the previous state is recoverable from this node's own output with one follow-up call. Sending the same set again, in any case or order, writes nothing and returns empty added and deleted lists. Use Uploadcare: Update File Tags instead when you only want to add or remove a few.

Uploadcare: Store File

uploadcare_store_file

Make one file permanent. Every Uploadcare file is temporary when it arrives and is deleted within 24 hours unless it is stored, so this is the call that turns a successful upload into a file that still exists tomorrow. It destroys nothing and can be run at any point inside the 24-hour window. Returns the file's full record with datetime_stored set. There is no matching un-store endpoint: the only way out of the stored state is Uploadcare: Delete File, which is permanent.

Uploadcare: Store Files (Bulk)

uploadcare_store_files_bulk

Make up to 100 files permanent in one call. The response splits into result, the file records that were stored, and problems, a map of the UUIDs that could not be: incomplete ids, ids from another project, or files that no longer exist. A partial failure still returns HTTP 200, so check data.problems rather than the status code.

Uploadcare: Update File Tags

uploadcare_update_file_tags

Add and remove tags on a file in one atomic operation, leaving everything else alone. Deletions are applied first, then additions, so a tag can be removed and re-added in the same call. Tags already present in add are skipped and tags absent from the file in delete are ignored, both silently. The request fails with 400 if the result would exceed 50 tags. An empty body is valid and simply returns the current state.

Uploadcare: Update Metadata Key

uploadcare_update_metadata_key

Set one metadata value on a file, creating the key if it does not exist (HTTP 201) or overwriting it if it does (HTTP 200). The request body is a bare JSON string, which the runner builds from the value field. Overwriting keeps no history, so read the old value first if the workflow may need it back.

Uploadcare: Update Webhook

uploadcare_update_webhook

Change a webhook subscription's target URL, event, active flag or signing secret. Fields left blank are not sent, so the rest of the subscription is untouched. Flipping is_active to false is the reversible way to stop deliveries without deleting the subscription and losing its signing secret. Request body is form-encoded, not JSON.

Uploadcare: Upload File from URL

uploadcare_upload_from_url

Hand Uploadcare a publicly reachable URL and it fetches the file server-side. This is the automation-native way to get bytes into a project: no file ever passes through the workflow. Returns a TOKEN, not a file id - feed it to Uploadcare: Get Upload Status to get the UUID once the fetch completes (the response can also come back as finished file info directly when duplicate checking matched an earlier upload). Remember that an uploaded file is TEMPORARY: leave store blank and the project's autostore setting decides, and if that is off the file is gone within 24 hours. This node runs against upload.uploadcare.com with the project's PUBLIC key, not the signed REST scheme.

Using the integration

On the automation canvas

Uploadcare nodes chain with every other node. A form submission carrying a file URL can run Uploadcare: Upload File from URL, poll Uploadcare: Get Upload Status until a UUID exists, make it permanent with Uploadcare: Store File, and write the UUID and CDN URL into a Mattering database row beside the record it belongs to. A scheduled sweep can run Uploadcare: Search Files and open a task for anything that arrived without the tags your process expects. Two values do most of the wiring: the UUID, which most fields offer as a picker sourced from Uploadcare: List Files, and the token or request id that every asynchronous node hands back in place of a result.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. The nineteen read nodes plus the store, tag and metadata nodes are the comfortable surface to hand an agent: it can find a file with Uploadcare: Search Files, read what is on it with Uploadcare: Get File, and write back what it learned with Uploadcare: Update File Tags. Keep the four destructive nodes behind conditions or approval steps. Uploadcare publishes an MCP server of its own, and it is worth knowing about before you choose: for an assistant helping you work with Uploadcare inside your editor or client config, the vendor's server is the closer fit. This integration is the operations side of the same platform: bulk storing, webhook subscriptions, conversion polls and the four Add-Ons, running as canvas steps as well as over MCP, with the credential held once in the workspace rather than in each person's local config.

Uploaded, stored, deleted, and the path that lies about which

Three states, and the naive reading is wrong in both directions. A file arrives UNSTORED, which is a countdown rather than a state: Uploadcare deletes it within 24 hours unless Uploadcare: Store File runs or the project has Auto file storing on. Storing is ADDITIVE, destroys nothing, and can run at any point inside that window, including in bulk for up to 100 files with Uploadcare: Store Files (Bulk). What does not exist anywhere in version 0.7 is an un-store: there is no endpoint that returns a stored file to temporary. The trap is that Uploadcare: Delete File sits on a path that reads like the inverse of storing and is not. It is a permanent delete: it sets a removal timestamp, clears the original file URL, and replaced the older delete endpoint in version 0.7. There is no restore endpoint. Two further details matter for takedowns: a deleted file stays LISTABLE, so the surviving metadata row is not the file coming back, and a delete does not invalidate the CDN cache, so an edge can keep serving the file for as long as that entry lives.

Everything asynchronous hands back a handle

Four families of node return a reference rather than a result, and each has its own poll. Uploadcare: Upload File from URL returns a TOKEN that is explicitly not a file id, and Uploadcare: Get Upload Status turns it into one: the status moves through waiting and progress before reaching success, at which point the response widens into full file info including the UUID. The Add-On execute nodes return a request id for their matching status node. Uploadcare: Convert Document and Uploadcare: Convert Video return tokens for their status nodes. The rule that follows is simple: nothing downstream should reference a UUID before the poll says it exists. A second habit belongs with it. Partial success answers HTTP 200 on bulk store, bulk delete and both conversions, with the response split into a result and a problems map, so branch on the problems map rather than on the status code or a half-failed batch reads as a clean run.

Tags, metadata, and the fact there are no folders

Uploadcare has no directory tree, so findability is entirely tags, metadata and search. Uploadcare: Update File Tags adds and removes in one atomic operation and leaves the rest alone, which makes it the safe default; deletions are applied before additions, so a tag can be removed and re-added in the same call. Uploadcare: Replace File Tags swaps the ENTIRE set and an empty list clears every tag, though it is still classed as a reversible write because the response returns the exact deleted list, which means the previous state is recoverable from the node's own output with one follow-up call. Uploadcare: Update Metadata Key attaches arbitrary values, typically an id from your own system. Four limits to design around: 50 metadata keys per file with 64-character keys and 512-character values, 50 tags per file at 100 characters each, tags normalized on write with an invalid tag failing the whole upload, and metadata that is untrusted input because whoever uploaded the file supplied it, so escape it for wherever it ends up and never put sensitive values in it.

Search, and where it stops

Uploadcare: Search Files queries filename, metadata, MIME type, UUID and tags with filtering on size, upload date and whether the file is an image. It is a POST because the query is a structured document, but it reads and changes nothing. Four constraints decide whether it will work for your case. Indexing is asynchronous, so newly uploaded files may not appear immediately and upload-then-search in one run is a race. Full-text terms need four or more characters. Its paging is offset-shaped with the offset plus the limit capped at 1000, so search cannot walk past the first thousand matches and the fix for a broad query is a narrower one rather than more paging. And fuzzy matching significantly increases query latency in the vendor's own words, so leave it off for scheduled runs. Uploadcare: List Files is the other route: it pages by following the absolute next and previous URLs the response returns, which carry their own cursor values and are not reconstructable by incrementing anything.

Webhooks: letting Uploadcare start a workflow

Uploadcare: Create Webhook subscribes a URL to a project event, so Uploadcare posts a notification when it happens. Point that target at an inbound webhook trigger in Mattering and the event becomes the start of a workflow: a file arrives in Uploadcare, the trigger fires, and the run stores it, screens it and files it away. Uploadcare: List Webhooks shows what exists, including each subscription's event, active flag, payload version and signing secret, and its response is a bare array. Uploadcare: Update Webhook changes a subscription in place, and setting it inactive is the reversible way to stop delivery. Uploadcare: Delete Webhook is the one to be careful with, and the reason is structural: it is keyed by TARGET URL alone, while a target URL is required unique only per project and event type. One receiver serving three events is three subscriptions, and one delete call can take all of them, with a response that looks identical either way.

Groups, conversion and CDN transformations

Uploadcare: Create Group bundles already-uploaded files so they can be addressed with one id and one CDN URL. Groups are IMMUTABLE: there is no add-to-group or remove-from-group call anywhere in the API, so changing the contents means a new group with a new id, and Uploadcare: Get Group can return nulls in its files array where a member has since been deleted, so guard before iterating. Group creation also does not store the members, so temporary files keep their own 24-hour clock and can expire out of a group. For conversion, run Uploadcare: Get Document Conversion Info first to see what a file is and which target formats it supports, then queue with Uploadcare: Convert Document or Uploadcare: Convert Video, remembering that each path entry is a source UUID followed by its operator and that a bare UUID with no operator lands in problems rather than result. Image transformations themselves are CDN URL operators rather than API endpoints, so there is nothing to call for them: Uploadcare: Copy File to Uploadcare Storage is how a transformed version becomes a stored file with a new UUID, and Uploadcare: Copy File to Custom Storage writes to a connected S3 bucket.

Troubleshooting

Files uploaded by an automation are gone the next day
They were never stored. Every Uploadcare file arrives temporary and is deleted within 24 hours unless it is stored or the project has Auto file storing enabled, and nothing about that reads as a failure: every call in the run returned a success. Run Uploadcare: Get Project and check autostore_enabled. If it is false, add Uploadcare: Store File to the same workflow that uploads, or Uploadcare: Store Files (Bulk) for up to 100 at a time. Storing is additive and destroys nothing, so run it as early in the workflow as you can. Note that creating a group does not store its members either, so temporary files can expire out of a group that looks complete.
Test Connection fails with a 401 or 403
That is the signature or the clock rather than the endpoint. Three things to check in order. Re-copy both keys from the project's API keys page, watching for leading or trailing whitespace, and confirm they come from the SAME project, since a public key and a secret key from different projects are each individually valid and will never sign correctly together. Then check the machine time: Uploadcare rejects a request whose timestamp is more than 15 minutes from its own clock regardless of a correct signature, so significant clock skew produces exactly this failure. A 406 rather than a 401 or 403 is a different repair: that one is about the version header, not the credential.
Calls succeed but the response shape is not what the node described
Check that nothing is overriding the API version. Uploadcare has eight documented versions and supports exactly one, and the deprecated ones still ANSWER rather than failing, with HTTP 200 and a DIFFERENT shape: an older version returns image and video info blocks where the current one returns a single content info block, and a differently named block for Add-On results. A workflow reading the current paths gets nothing, no error is raised anywhere, and the integration looks healthy. Mattering pins the supported version on every request and exposes no field that can change it, so if you are seeing an older shape, the call is not coming from this integration.
A bulk store, bulk delete or conversion reports success but some items did not happen
Read the problems map rather than the status code. Bulk store, bulk delete, Uploadcare: Convert Document and Uploadcare: Convert Video all answer HTTP 200 on a PARTIAL success, splitting the response into result for what worked and problems for what did not, keyed by the id or path that failed. A workflow branching on the status code treats a half-failed batch as a clean run. Common entries in that map are incomplete ids, ids belonging to another project, and for conversions a bare UUID sent without its operator segment. Bulk store and bulk delete also cap at 100 files per call, which the node enforces with a readable message rather than letting it fail at Uploadcare.
A UUID from an upload does not resolve
It is probably a token, not a UUID. Uploadcare: Upload File from URL returns a token that Uploadcare explicitly states is not a file id, and the real UUID does not exist until Uploadcare: Get Upload Status reports success, at which point the response widens into full file info. The same pattern applies across the API: Add-On execute nodes return a request id, and conversions return a token. Wire the poll node in between rather than referencing the id straight from the submit step, and give the poll somewhere to branch when the status comes back as an error rather than a result.
An Add-On status says done but the result is empty
For three of the four Add-Ons that is expected: the status node returns only a status, and the actual output is written into the file's appdata. Read it back with Uploadcare: Get File asking for appdata to be included, after the status reads done. The exception is Uploadcare: Get Background Removal Status, which does carry a payload worth reading: the UUID of the NEW background-free image, which is a different file from the one you submitted. If the Add-On itself never runs, check your plan: the four Add-Ons are third-party services billed through Uploadcare and are the most likely surface here to be plan-gated.
Copy to custom storage returns 200 and the bucket does not change
That is the documented meaning of 200 on that endpoint, and it is the failure mode where a scheduled copy reports success forever. 201 means the file was copied; 200 means a file with that name ALREADY EXISTED at the destination and it was not overwritten. Branch on the status code rather than on success, and give each copy a distinct target name if the workflow is meant to write a new file every run. A related shape on the local copy node: the immediate response can carry provisional values, with a size of zero and a generic MIME type, while the copy finishes, so re-read with Uploadcare: Get File when you need settled values.
A deleted file is still listed, or still loads from its CDN URL
Both are expected and neither means the delete failed. Deleted files stay listable, and the file list can be asked for removed files with a removed count alongside the stored and unstored totals, because Uploadcare keeps the metadata row after the bytes are gone. Separately, a delete does not invalidate the CDN cache, so an edge can keep serving the file for as long as that entry lives, which matters if the delete was a takedown. There is no restore endpoint in version 0.7, so treat the surviving row as a record of what was deleted rather than as a way back.
Deleting one webhook stopped more deliveries than expected
Uploadcare: Delete Webhook is keyed by TARGET URL and nothing else, while a target URL is only required to be unique per project and event type. So one receiver subscribed to three events is three subscriptions, and one delete call removes all of them, with a response indistinguishable from removing a single one. Run Uploadcare: List Webhooks first to see exactly what shares that URL. Where the intent is to pause rather than remove, Uploadcare: Update Webhook can set a subscription inactive, which is reversible and leaves the signing secret in place; deleting loses the subscription and any auto-generated signing secret with it.
Search does not find a file that definitely exists
Four documented constraints cause this, in the order they usually bite. Indexing is asynchronous, so a file uploaded moments ago may not be searchable yet and upload-then-search in one run is a race. Full-text terms need four or more characters. A field cannot appear in both the phrase and the exact parts of a query. And paging is offset-shaped with the offset plus the limit capped at 1000, so a broad query cannot be walked past its first thousand matches; the fix is a narrower query rather than more pages. If the file is old and the query is fine, use Uploadcare: List Files with the cursor URLs the response returns, which pages the whole project without the search index in the way.

Uploadcare is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products