Asset Tagging System

The tagging system provides a flexible way to organize, categorize, and filter assets across your Digital Asset Manager. Tags are lightweight, user-created labels that help you quickly locate and group related media files.

Overview

Tags are: - User-managed — Create and apply tags freely to any asset - Searchable — Filter entire asset library by single or multiple tags - Autocompleted — Suggestions based on existing tags across your library - Persistent — Stored in the database for instant access - Lowercase-normalized — Consistent across all assets

Quick Start

Adding Tags to an Asset

  1. Open any asset in the Asset Detail View
  2. Click the Edit button next to "Tags" section
  3. Type a tag name (e.g., client, 2024-project, video-edit)
  4. Press Enter or click Add button
  5. See suggested tags from your library below the input
  6. Click Save Tags to persist or Cancel to discard

Filtering Assets by Tag

  1. In Asset Library Dashboard, scroll to the Tags section
  2. All available tags load as filter buttons
  3. Click any tag to instantly show only assets with that tag
  4. Click Clear to reset filters

Removing Tags

In tag editor mode, each tag has a × button to remove it before saving.

API Reference

List All Tags

GET /api/assets/tags/list

Response:

{
  "success": true,
  "tags": ["client", "video", "project-alpha", "2024"],
  "count": 4
}

Get Asset Tags

GET /api/assets/<asset_id>/tags

Response:

{
  "success": true,
  "asset_id": 123,
  "tags": ["video", "client"]
}

Update Asset Tags (Bulk Replace)

PUT /api/assets/<asset_id>/tags
Content-Type: application/json

{
  "tags": ["tag1", "tag2", "tag3"]
}

Response:

{
  "success": true,
  "asset_id": 123,
  "tags": ["tag1", "tag2", "tag3"],
  "message": "Updated 3 tags"
}

Add Single Tag

POST /api/assets/<asset_id>/tags
Content-Type: application/json

{
  "tag": "new-tag"
}

Response:

{
  "success": true,
  "asset_id": 123,
  "tags": ["tag1", "tag2", "new-tag"],
  "message": "Added tag: new-tag"
}

Remove Single Tag

DELETE /api/assets/<asset_id>/tags/<tag_name>

Response:

{
  "success": true,
  "asset_id": 123,
  "tags": ["tag1", "tag2"],
  "message": "Removed tag: new-tag"
}

Filter Assets by Tag

GET /api/assets/filter?tag=video&page=1&limit=20

Response:

{
  "success": true,
  "tag": "video",
  "assets": [
    {
      "id": 101,
      "title": "Project_Alpha_v2",
      "filename": "project_alpha_v2.jpg",
      "mime_type": "image/jpeg",
      "size": 4200000,
      "url": "...",
      "metadata": "{...}",
      "created_at": "2025-12-15T10:30:00",
      "tags": "video,client"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 5
}

Database Schema

Tags are stored in the assets table's tags column (TEXT):

-- Column definition
tags TEXT DEFAULT ''

-- Format: comma-separated, lowercase
-- Example: "client,video,project-alpha,2024"

Storage Details

Field Type Notes
tags TEXT Comma-separated, lowercase tags. Empty string if no tags.

Why comma-separated? - Simple, human-readable format - Efficient LIKE-based searching - No need for separate tags table for basic use - Easy to extend to junction table later for multi-user permissions

Best Practices

Naming Conventions

✓ Lowercase         client, video-edit, 2024-q1
✓ Use hyphens       project-alpha, high-priority
✓ Descriptive       color-grading, client-review

✗ Mixed case        Client, VideoEdit (normalized to lowercase)
✗ Spaces            "video edit" → use hyphen instead
✗ Special chars     avoid @#$% except hyphens

Tag Organization Strategy

By Client/Project:

client-abc, client-xyz, project-mars-city

By Media Type:

video, image, audio, document

By Status:

draft, approved, archived, published

By Studio/Department:

film-editing, photography, graphic-arts, podcasting

Combine tags for powerful filtering: - Asset tagged video,client,approved shows in filters for any of these - Multiple tag filters could be added in future

Use Cases

Marketing Team

  • Tag assets by campaign: campaign-2024-spring, campaign-holiday
  • Tag by deliverable: social-media, web, print
  • Tag by status: approved, draft, archived

Film Production

  • Tag by scene: scene-01, scene-02
  • Tag by take: take-01, take-final
  • Tag by status: raw-footage, color-graded, final

Photography Studio

  • Tag by photoshoot: photoshoot-product-2024, photoshoot-event-dec
  • Tag by edit status: unedited, edited, retouched
  • Tag by usage: website, print-catalog, client-delivery

Asset Library Management

  • Tag by source: from-google-drive, from-network-share, uploaded-local
  • Tag by date: 2024-q1, 2024-q2, archive-2023
  • Tag by quality: high-res, web-ready, thumbnail-only

Limitations & Future Enhancements

Current Limitations

  • Single tag per search — Filter by one tag at a time
  • No tag hierarchy — No parent/child tag relationships
  • No permissions — All users see and can edit all tags
  • No tag descriptions — Tags are label-only

Planned Enhancements

  1. Multi-tag filtering — ?tags=video,client,approved
  2. Tag hierarchy — video/footage, video/edit
  3. Tag analytics — Most-used tags, tag cloud visualization
  4. Smart suggestions — Suggest tags based on file type or content
  5. Tag validation — Admin-controlled tag whitelist
  6. Bulk tag operations — Apply tags to multiple assets at once
  7. Tag synonyms — hdv → video, pic → image
  8. User-specific tags — Per-user tag visibility and permissions

Troubleshooting

Tags Not Appearing

Problem: Added a tag but it's not showing in the filter list.

Solution: - Reload the page — filter buttons are loaded on page init - Verify tag was saved — check Asset Detail View confirmation - Check spelling — tags are case-insensitive but must match exactly

Tag Suggestions Not Loading

Problem: Autocomplete suggestions are empty.

Solution: - No other assets have tags yet — create a few tagged assets first - Check browser console for errors - Verify /api/assets/tags/list is responding (check Network tab)

Can't Edit Tags

Problem: Edit button doesn't work or tags won't save.

Solution: - Ensure you're logged in — tag edit requires authentication - Check for errors in browser console - Try refreshing the page - Verify server is running (check Flask logs)