File tags

Each file can carry a list of string tags. Tags are set at upload time or managed via dedicated REST API endpoints. They appear in all file info responses and can be used as a filter in file search.

Normalization

All tag input is normalized before storage:

Limits and allowed characters

All limits are evaluated after normalization and deduplication. Tags that contain any other character (spaces, Unicode, +, @, etc.) are rejected with HTTP 400.

Setting tags at upload time

Pass tags as a form field alongside other upload parameters for POST /base/ (direct upload) and POST /multipart/start/. The value is a comma-separated list of tag names.

$
curl -L 'https://upload.uploadcare.com/base/' \
>
     -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>
     -F "UPLOADCARE_STORE=1" \
>
     -F "file=@photo.jpg" \
>
     -F "tags=cat,animal,cute"

Validation errors (too many tags, tag too long, invalid characters) return HTTP 400 and the upload does not proceed:

1
{
2
  "error": {
3
    "status_code": 400,
4
    "content": "Too many tags: 51 (max 50).",
5
    "error_code": "UploadViewsError"
6
  }
7
}

The standard upload response does not include tags. To read tags after upload, use GET /files/{uuid}/ or GET /files/{uuid}/tags/.

Tags in file info

When tags are enabled, the tags field is included in all file info responses at API version 0.7:

1
{
2
  "uuid": "...",
3
  "original_filename": "photo.jpg",
4
  "tags": ["cat", "animal"],
5
  ...
6
}

A file with no tags returns "tags": [].

Endpoints that include tags:

• GET /files/{uuid}/ — single file info
• GET /files/ — file list
• Webhook payloads

REST API

All tag endpoints:

• Require Accept: application/vnd.uploadcare-v0.7+json
• Require standard Uploadcare authentication (secret key)
• Are scoped to the authenticated project
• Return 404 for files in other projects or removed files

Get tags

GET /files/{uuid}/tags/

Returns the current tag list.

$
curl -L 'https://api.uploadcare.com/files/$UUID/tags/' \
>
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
     -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY"

Response 200:

1
{"tags": ["cat", "animal"]}

Returns {"tags": []} for a file with no tags.

Replace tags

PUT /files/{uuid}/tags/

Replaces the entire tag set. Previous tags not in the new list are deleted. An empty array clears all tags.

$
curl -L -X PUT 'https://api.uploadcare.com/files/$UUID/tags/' \
>
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
     -H "Content-Type: application/json" \
>
     -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
     -d '{"tags": ["cat", "animal", "cute"]}'

Response 200:

1
{
2
  "tags": ["cat", "animal", "cute"],
3
  "added": ["animal", "cute"],
4
  "deleted": ["old-tag"]
5
}

• tags — resulting tag list in storage order
• added — tags in the new set but not in the previous set (sorted alphabetically)
• deleted — tags in the previous set but not in the new set (sorted alphabetically)

Calling PUT with the same set of tags (regardless of input case or order) is safe and produces no write — added and deleted will both be empty.

Update tags (add and/or remove)

PATCH /files/{uuid}/tags/

Adds and/or removes tags in a single atomic operation. Both add and delete are optional and default to []. Delete is applied first, then add — so a tag can be removed and re-added in one request.

$
curl -L -X PATCH 'https://api.uploadcare.com/files/$UUID/tags/' \
>
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
>
     -H "Content-Type: application/json" \
>
     -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
>
     -d '{"add": ["dog", "outdoor"], "delete": ["cat"]}'

Response 200:

1
{
2
  "tags": ["animal", "dog", "outdoor"],
3
  "added": ["dog", "outdoor"],
4
  "deleted": ["cat"]
5
}

• tags — resulting tag list in storage order
• added — tags that were not previously present and were added
• deleted — tags that were present and were removed

Tags in add that already exist are silently skipped. Tags in delete that are not present are silently ignored. An empty body {} is valid and returns the current state unchanged. If the resulting count would exceed 50, the request fails with 400.

Filtering by tags in file search

Use the tags key in POST /files/search/ to filter files by their tags:

1
{
2
  "tags": {
3
    "any": ["cat", "dog"],
4
    "all": ["outdoor"],
5
    "none": ["archived"]
6
  }
7
}

All three keys are optional, but at least one must be non-empty. Tag values are normalized before the search query is built.

Get $YOUR_PUBLIC_KEY and $YOUR_SECRET_KEY from API keys.