Tags API
Endpoints for managing tags on media files.
List All Tags
Get all tags in the library with usage counts.
Response
[
{
"id": 1,
"name": "vacation",
"color": "#3b82f6",
"itemCount": 42,
"createdAt": "2026-04-03T18:25:19Z"
},
{
"id": 2,
"name": "family",
"itemCount": 128,
"createdAt": "2026-04-03T18:25:19Z"
}
]
Get File Tags
Get tags assigned to a specific file.
Parameters
| Parameter | Type | Description |
|---|---|---|
| path | string | URL-encoded file path |
Response
Add Tag to File
Add a tag to a single file.
Request
Response
Remove Tag from File
Remove a tag from a single file.
Request
Response
Replace All Tags for a File
Replace the full tag set for a file.
Request
Response
Batch File Tag Lookup
Get tags for multiple files in one request.
Request
Response
{
"photos/vacation/beach.jpg": ["vacation", "beach"],
"photos/vacation/sunset.jpg": ["vacation", "sunset"]
}
Related Tag Suggestions
Return tags that frequently co-occur with the provided tags. The tagging UI uses this endpoint for related suggestions such as Suggested Next and Suggested Together.
Request
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
tags | array of strings | Yes | Tags already selected or already applied |
exclude | array of strings | No | Additional tag names to suppress from the response |
limit | integer | No | Maximum number of suggestions to return |
Response
[
{
"name": "beach",
"itemCount": 42,
"relatedCount": 12
},
{
"name": "summer",
"itemCount": 30,
"relatedCount": 7
}
]
relatedCount is the number of items where the suggested tag appears alongside the requested tags. itemCount is the total number of items using that tag anywhere in the library.
Recent tags shown in the UI are tracked client-side and are not returned by this endpoint.
Bulk Add Tag
Add a tag to multiple files at once.
Request
{
"paths": [
"photos/vacation/beach.jpg",
"photos/vacation/sunset.jpg",
"photos/vacation/hotel.jpg"
],
"tag": "vacation"
}
You can also send a tags array to apply multiple tags in one request.
Response
Bulk Remove Tag
Remove a tag from multiple files at once.
Request
Like bulk add, this endpoint also accepts a tags array.
Response
Tag Management Endpoints
Get All Tags with Counts
Get all tags with usage statistics.
Response
[
{
"name": "vacation",
"color": "#3b82f6",
"count": 42
},
{
"name": "family",
"color": "",
"count": 28
},
{
"name": "unused",
"color": "#10b981",
"count": 0
}
]
Tags are sorted by count (descending), then name (alphabetically).
Get Unused Tags
Get all tags that have no file associations.
Response
Rename Tag Everywhere
Rename a tag and update all file associations.
Parameters
| Parameter | Type | Location | Description |
|---|---|---|---|
| tag | string | path | Current tag name (URL-encoded) |
Request
Response
Special Cases:
- If the new name already exists, tags are merged automatically
- Case-only changes are supported (e.g., "animal" → "Animal")
- Same name returns 0 affected files (no-op)
Delete Tag Everywhere
Delete a tag from all file associations.
Parameters
| Parameter | Type | Location | Description |
|---|---|---|---|
| tag | string | path | Tag name (URL-encoded) |
Response
Get Files for a Tag
Return media files associated with a tag.
Response
{
"files": [
{
"id": 101,
"name": "beach.jpg",
"path": "photos/vacation/beach.jpg",
"parentPath": "photos/vacation",
"type": "image"
}
]
}
For exact schemas and limit details, see the OpenAPI specification.