Skip to content

Tags API

Endpoints for managing tags on media files.

List All Tags

Get all tags in the library with usage counts.

GET /api/tags

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.

GET /api/tags/file?path={filePath}

Parameters

Parameter Type Description
path string URL-encoded file path

Response

["vacation", "beach", "2024"]

Add Tag to File

Add a tag to a single file.

POST /api/tags/file

Request

{
    "path": "photos/vacation/beach.jpg",
    "tag": "vacation"
}

Response

{
    "status": "ok"
}

Remove Tag from File

Remove a tag from a single file.

DELETE /api/tags/file

Request

{
    "path": "photos/vacation/beach.jpg",
    "tag": "vacation"
}

Response

{
    "status": "ok"
}

Replace All Tags for a File

Replace the full tag set for a file.

PUT /api/tags/file

Request

{
    "path": "photos/vacation/beach.jpg",
    "tags": ["vacation", "beach", "sunset"]
}

Response

{
    "status": "ok"
}

Batch File Tag Lookup

Get tags for multiple files in one request.

POST /api/tags/query

Request

{
    "paths": ["photos/vacation/beach.jpg", "photos/vacation/sunset.jpg"]
}

Response

{
    "photos/vacation/beach.jpg": ["vacation", "beach"],
    "photos/vacation/sunset.jpg": ["vacation", "sunset"]
}

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.

POST /api/tags/suggestions

Request

{
    "tags": ["vacation"],
    "exclude": ["summer"],
    "limit": 5
}

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.

POST /api/tags/bulk

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

{
    "success": 3,
    "failed": 0,
    "errors": []
}

Bulk Remove Tag

Remove a tag from multiple files at once.

DELETE /api/tags/bulk

Request

{
    "paths": ["photos/vacation/beach.jpg", "photos/vacation/sunset.jpg"],
    "tag": "vacation"
}

Like bulk add, this endpoint also accepts a tags array.

Response

{
    "success": 2,
    "failed": 0,
    "errors": []
}

Tag Management Endpoints

Get All Tags with Counts

Get all tags with usage statistics.

GET /api/tags/stats

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.

GET /api/tags/unused

Response

["unused", "orphan", "temp"]

Rename Tag Everywhere

Rename a tag and update all file associations.

PUT /api/tags/{tag}

Parameters

Parameter Type Location Description
tag string path Current tag name (URL-encoded)

Request

{
    "newName": "vacation"
}

Response

{
    "status": "ok"
}

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.

DELETE /api/tags/{tag}

Parameters

Parameter Type Location Description
tag string path Tag name (URL-encoded)

Response

{
    "status": "ok"
}

Get Files for a Tag

Return media files associated with a tag.

GET /api/tags/{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.