Home/Blog/Auto-tag images in n8n with Uploadcare object recognition

Auto-tag images in n8n with Uploadcare object recognition

Inย this guide, youโ€™ll learn how toย auto-tag every image upload inย n8n with the Uploadcare Object Recognition add-on. Byย the end, youโ€™ll have aย workflow where each file.uploaded event runs the add-on and writes high-confidence labels toย your database orย CMS.

The Object Recognition add-on isย an Uploadcare REST API feature that runs anย uploaded image through AWS Rekognition and stores the detected labels onย the file. Each label carries a Name and a Confidence score, soย you can keep only the tags the model isย sure about.

For the basics onย connecting n8n toย Uploadcare, see the main n8n + Uploadcare integration guide.

Ifย you want aย fully ready-to-import workflow.json version ofย this tutorial, you can find itย inย the image-tagging folder ofย the repo.

Prerequisites

Toย follow along with this tutorial, youโ€™ll need the following:

What weโ€™re building

  1. Anย Uploadcare webhook fires on file.uploaded and hits anย n8n Webhook node.
  2. n8n triggers the aws_rekognition_detect_labels add-on for that file UUID.
  3. The workflow polls the add-on status until itย reports done.
  4. n8n reads the labels from the fileโ€™s appdata and keeps only high-confidence tags.
  5. The tags are written toย yourย DB orย CMS for organization and search.
The n8n workflow for auto-tagging images with Uploadcareโ€™s Object Recognition add-onThe n8n workflow for auto-tagging images with Uploadcareโ€™s Object Recognition add-on

Stepย 1: Receive the upload event

The workflow starts when Uploadcare tells n8n aย file landed. Aย Webhook node gives you aย URL to register, andย a Set node pulls the file UUID out ofย the payload soย the rest ofย the workflow can reference itย cleanly.

Add the Webhook node

  1. Click the + button toย add aย new node and search for the Webhook node.
  2. Set the HTTP Method to POST.
  3. Copy the nodeโ€™s Production URL.
  4. Inย the Uploadcare Dashboard, goย toย API โ†’ Webhooks, paste the URL, and subscribe toย the file.uploaded event.

Uploadcare then POSTs aย JSON payload toย that URL onย every new upload. The JSON isย shaped like this:

{
  "event": "file.uploaded", 
  "data": {
    "uuid": "..."
  }
}
n8n Webhook node configured for the Uploadcare file.uploaded eventn8n Webhook node configured for the Uploadcare file.uploaded event

Extract the UUID

  1. Add aย Set node after the Webhook node and rename it Extract UUID.
  2. Add aย field, set its Name to uuid, and set its Type to String.
  3. For the value, enter the expression {{ $json.body.data.uuid }}.

This reads body.data.uuid from the incoming webhook payload, which isย where Uploadcare puts the file identifier, and stores itย asย aย clean uuid field. Every downstream node can then reference {{ $json.uuid }} without digging back into the raw event body.

n8n Set node extracting the file UUID from the webhook payloadn8n Set node extracting the file UUID from the webhook payload

Stepย 2: Trigger the Object Recognition add-on

The add-on runs server-side and asynchronously, soย you start itย withย an HTTP Request node. The execute call (Add-Ons REST API reference) doesnโ€™t return labels right away. Instead, itย returns a request_id that you poll in the next step.

Configure the execute request

  1. Add anย HTTP Request node after the Set node and rename it Execute Rekognition.
  2. Set the Method to POST.
  3. Set the URL to https://api.uploadcare.com/addons/aws_rekognition_detect_labels/execute/.
n8n HTTP Request node set toย POST the Object Recognition execute endpointn8n HTTP Request node set toย POST the Object Recognition execute endpoint

Add the authentication headers

Every Uploadcare REST API call needs the Authorization and Accept headers, and because this auth isย server-side only, never ship itย toย aย browser.

  1. Toggle Send Headers onย and set the Specify Headers field to Using Fields Below.
  2. Add aย header with Name Authorization and Value Uploadcare.Simple YOUR_PUBLIC_KEY:YOUR_SECRET_KEY.
  3. Add aย second header with Name Accept and Value application/vnd.uploadcare-v0.7+json.

Send the target UUID

  1. Toggle Send Body onย and set the Body Content Type to JSON.

  2. Set Specify Body to Using JSON.

  3. Enter this JSON body, where target isย the file the add-on should analyze:

    {
      "target": "{{ $json.uuid }}"
    }
  4. Open Options โ†’ Response and set Response Format to JSON.

Note: Uploadcareโ€™s REST API responds with the content type application/vnd.uploadcare-v0.7+json. n8n doesnโ€™t auto-detect that vendor +json type asย JSON, soย without Response Format set to JSON itย hands you the body asย aย raw string under a data field, and expressions like {{ $json.request_id }} come back empty. Set Response Format to JSON here and onย every Uploadcare REST call inย this workflow soย n8n parses the body and you can read its fields directly.

The response includes a request_id youโ€™ll use toย poll for completion inย the next step.

Stepย 3: Wait and poll for completion

Now that the add-on isย running, give itย aย moment and then check onย it.

Add aย Wait node

  1. Addย a Wait node after the execute request.
  2. Set itย toย wait for around 8 seconds, giving Rekognition time toย process the image.
n8n Wait node set toย pause for 8ย secondsn8n Wait node set toย pause for 8ย seconds

Check the add-on status

  1. Add anย HTTP Request node after the Wait node and rename it Check Add-on Status.

  2. Set the Method to GET.

  3. Set the URL toย the status endpoint, passing the request_id from the execute response:

    https://api.uploadcare.com/addons/aws_rekognition_detect_labels/execute/status/?request_id={{ $json.request_id }}
  4. Toggle Send Headers onย and add the same Authorization and Accept headers from Stepย 2.

  5. Open Options โ†’ Response and set Response Format to JSON, just asย inย Stepย 2, so {{ $json.status }} parses instead ofย arriving asย aย string under data.

n8n HTTP Request node polling the Object Recognition status endpointn8n HTTP Request node polling the Object Recognition status endpoint

Branch onย the result

  1. Addย an If node after the status check.
  2. Add aย condition comparing {{ $json.status }} to done.

When status equals done (the true output), the labels are ready, soย the workflow continues. Otherwise, route the false output back toย aย short Wait &ย Retry node that loops toย the status check.

Tip: Ifย aย file occasionally takes longer, this loop keeps polling instead ofย failing the moment a result isnโ€™t ready.

n8n Ifย node branching onย the done statusn8n Ifย node branching onย the done status

Stepย 4: Where doย the recognition results live?

The add-on stores its results onย the file itself, not inย the poll response, which only reports {"status": "done"}. The labels land in appdata.aws_rekognition_detect_labels.data.Labels, where each entry has a Name and a Confidence score, soย once the status reports done, you fetch the file toย read them.

Note: Two things toย watch out for:

  • The appdata field isย only returned when you ask for itย with ?include=appdata; aย plain GET /files/<UUID>/ comes back with appdata: null.

  • The labels array is Labels with aย capital L, because itย mirrors the raw AWS Rekognition response.

Fetch the file info

  1. Onย theย If nodeโ€™s true output, add anย HTTP Request node and rename it Get File Info.

  2. Set the Method to GET.

  3. Set the URL toย the file endpoint, using the UUID captured back inย Stepย 1, with the ?include=appdata query parameter soย the response carries the add-on results:

    https://api.uploadcare.com/files/{{ $(โ€™Extract UUIDโ€™).item.json.uuid }}/?include=appdata
  4. Toggle Send Headers onย and add the same Authorization and Accept headers from Stepย 2.

  5. Open Options โ†’ Response and set Response Format to JSON, just asย inย Stepย 2, soย n8n parses the body and appdata arrives asย anย object instead ofย aย string under data.

This reads the same file the add-on analyzed and returns the full file object (File REST API reference). The ?include=appdata parameter isย what makes Uploadcare attach the appdata.aws_rekognition_detect_labels.data.Labels array that the Object Recognition add-on wrote; withoutย it, appdata comes back null.

n8n HTTP Request node fetching the Uploadcare file info with appdatan8n HTTP Request node fetching the Uploadcare file info with appdata

Stepย 5: Filter tags byย confidence

Aย Code node turns the raw labels into aย tidy tag list, dropping anything below your threshold. Add aย Code node after the file fetch, set its language toย JavaScript, and enter the following:

const CONFIDENCE_THRESHOLD = 80;
const file = $input.first().json;
const labels = file?.appdata?.aws_rekognition_detect_labels?.data?.Labels || [];

const tags = labels
  .filter((label) => label.Confidence >= CONFIDENCE_THRESHOLD)
  .map((label) => label.Name);

return [
  {
    json: {
      uuid: file.uuid,
      cdnUrl: `https://2ta6v1zvst.ucarecd.net/${file.uuid}/`,
      tags,
      tagCount: tags.length,
    },
  },
];

The code above:

  • Sets a CONFIDENCE_THRESHOLD ofย 80ย so only labels the model isย reasonably sure about make the cut.
  • Reads the labels from appdata.aws_rekognition_detect_labels.data.Labels (capital L), defaulting toย anย empty array ifย the add-on returned nothing.
  • Keeps each labelโ€™s Name and discards its score, then returns aย single record with the uuid, aย ready-to-use cdnUrl, the filtered tags, and a tagCount.

Note: 2ta6v1zvst.ucarecd.net isย this projectโ€™s CDN domain. Find yours inย the Uploadcare Dashboard under Delivery โ†’ CDN Domain names, and use itย inย place ofย the shared ucarecdn.com host inย the URLs throughout this guide.

What the tags look like

Run aย real photo through this and you can watch the threshold doย its job. Aย car photo returns these high-confidence labels, while aย borderline Sports Car guess atย 58% confidence gets filtered out:

{
  "uuid": "<file-uuid>",
  "cdnUrl": "https://2ta6v1zvst.ucarecd.net/<file-uuid>/",
  "tags": ["Machine", "Wheel", "Tire", "Alloy Wheel", "Car", "Car Wheel", "Spoke", "Vehicle", "Person"],
  "tagCount": 9
}

That single dropped label isย the difference between aย clean tag set and aย noisy one, which isย exactly what the CONFIDENCE_THRESHOLD controls.

Stepย 6: Store the tags

With aย clean tag list ready, aย Set node assembles the final record andย a Data Table node stores itย inย n8nโ€™s built-in, lightweight datastore, noย external database toย run.

Assemble the record

  1. Add aย Set node after the Code node and rename it Build Tag Record.
  2. Add fields for uuid, cdnUrl, and tags, mapping each from the Code nodeโ€™s output.
n8n Set node assembling the uuid, cdnUrl, and tags recordn8n Set node assembling the uuid, cdnUrl, and tags record

Store the tags inย aย Data Table

n8nโ€™s built-in Data Tables give you aย local, lightweight store with noย extra service toย run, aย good fit for this workflow. First create the table:

  1. From the n8n Overview, open the Data tables tab and select Create data table.
  2. Name it image_tags, then add three string columns: uuid, cdnUrl, and tags.

Then write each tagged image intoย it:

  1. Add aย Data Table node after the Set node and rename it Store Tags (Data Table).
  2. Set the Operation toย Insert row and choose your image_tags table.
  3. With Map Each Column Manually, map each column toย the record:
    • uuid โ†’ {{ $json.uuid }}
    • cdnUrl โ†’ {{ $json.cdnUrl }}
    • tags โ†’ {{ $json.tags.join(", ") }} โ€” the column isย text, soย join the array into aย string.

Each new upload now appends aย row you can browse right inย the n8n UI.

n8n Data Table node inserting the uuid, cdnUrl, and tags rown8n Data Table node inserting the uuid, cdnUrl, and tags row

Note: Data Tables ship with recent n8n versions. Onย anย older release, orย ifย you want aย store shared across systems, swap this node for anย HTTP Request (orย the Postgres node) that writes the same uuid, cdnUrl, and tags toย your database, CMS, orย API. From here you can power faceted search, auto-foldering, orย alerting whenever aย specific label appears.

Conclusion

Inย this guide, youโ€™ve learned how toย turn aย new upload into high-confidence tags automatically: triggering the Object Recognition add-on, filtering its labels byย confidence, and storing the result for later use.

Feel free toย import the workflow from the image-tagging folder ofย the repo and adapt itย toย your own database, CMS, orย API.

Some possible next steps:

  • Faceted search: Index the tags array soย users can filter the media library byย label.
  • Auto-foldering: Route files into collections based onย their top label.
  • Label alerts: Notify aย channel whenever aย specific label, such asย aย brand orย aย person, appears.

For more workflows built onย the same execute-then-poll REST API pattern, see how toย convert documents toย PDF automatically inย n8n.

FAQs

Doย Iย need toย poll instead ofย relying onย the webhook alone?

Yes. The file.uploaded webhook tells you aย file exists, but the Object Recognition add-on runs asynchronously and finishes aย little later. The execute call returns a request_id, and polling the status endpoint with that request_id confirms the labels are ready before you read them.

How doย I tune which tags Iย keep?

Adjust the CONFIDENCE_THRESHOLD inย the Code node, which compares against each labelโ€™s Confidence score. For aย clean, low-noise tag set, use aย higher value such asย 90ย toย keep only the most certain labels; for broader coverage, use aย lower value toย capture more tags atย the cost ofย some noise.

Where does the Object Recognition add-on store its results?

Onย the fileโ€™s appdata, not inย the poll response. After the add-on completes, GET /files/<UUID>/?include=appdata returns appdata.aws_rekognition_detect_labels.data.Labels (capital L), where each entry has a Name and a Confidence value. Without the ?include=appdata parameter, appdata comes back null.

Why are myย tags empty even though the add-on ran?

Three things cause anย empty tag list, and any one ofย them isย enough:

  • Response Format isnโ€™t set toย JSON. Uploadcare replies with application/vnd.uploadcare-v0.7+json, which n8n leaves asย aย raw string under a data key unless the HTTP Request nodeโ€™s Response Format is JSON. While itโ€™s aย string, appdata isย unreachable.
  • ?include=appdata isย missing from the Get File Info URL, soย the response has appdata: null.
  • The labels key is Labels, not labels (capital L, mirroring the AWS Rekognition response).

Fix all three and the same image returns its labels, for example Person, Man, and Portrait at high confidence.

Ready to get started?

Join developers who use Uploadcare to build fileย handling quickly andย reliably.

Sign up for free