Tagging System

GatherHub includes a flexible tagging system that allows you to organize and categorize your download jobs. Tags make it easier to find related content and manage your archives more efficiently.

How Tags Work

Tags in GatherHub are simple text labels that can be attached to any job. A job can have multiple tags, and the same tag can be applied to multiple jobs, creating a many-to-many relationship.

Tags are stored in the database and are preserved even if the job status changes or if the job is retried.

Adding Tags to Jobs

There are several ways to add tags to jobs:

From the Job Details Page

1. Navigate to the job details page by clicking on a job in the jobs list
2. Find the "Tags" section
3. Click the "Add Tag" button
4. Enter a tag name or select from existing tags
5. Click "Save" or press Enter

From the Jobs List

1. On the Jobs page, find the job you want to tag
2. Click the "Actions" button for that job
3. Select "Add Tag" from the dropdown menu
4. Enter a tag name or select from existing tags
5. Click "Save" or press Enter

Using the API

You can also add tags programmatically:

POST /api/jobs/{id}/tags
Content-Type: application/json

{
  "tag": "tutorial"
}

Removing Tags

From the Job Details Page

1. Navigate to the job details page
2. In the "Tags" section, find the tag you want to remove
3. Click the "×" next to the tag
4. Confirm the removal if prompted

Using the API

DELETE /api/jobs/{id}/tags/{tag_name}

Filtering by Tags

One of the main benefits of tags is the ability to filter jobs based on them:

From the Jobs Page

1. Go to the Jobs page
2. Find the "Tags" filter dropdown in the filters section
3. Select one or more tags to filter by
4. Click "Apply Filters"

The jobs list will update to show only jobs that have all the selected tags.

Combining Tag Filters with Other Filters

You can combine tag filters with other filters like status or media type:

• Filter for all "tutorial" videos that are completed
• Find all "important" jobs that have failed
• Identify all "work" and "project" related jobs of a specific media type

Tag Management

While tags are created ad-hoc when you add them to jobs, you can see a complete list of all available tags:

Viewing All Tags

1. Go to the Jobs page
2. Click on the Tags filter dropdown
3. All existing tags in the system will be shown in the dropdown

You can also view tags through the API:

GET /api/tags

Tag Naming Conventions

GatherHub doesn't enforce specific tag naming conventions, but here are some recommendations:

• Use lowercase for consistency (tags are case-sensitive)
• Use short, descriptive names
• Use hyphens for multi-word tags (e.g., "video-tutorial" instead of "video tutorial")
• Develop a consistent naming scheme for your own organization system

Example Tagging Strategies

Here are some effective ways to use tags:

Content Type Tags

• tutorial, documentation, article, reference
• video, audio, text, image

Topic or Subject Tags

• programming, design, science, history
• python, golang, javascript

Source Tags

• github, youtube, medium, twitter
• personal, work, research

Priority Tags

• important, urgent, reference, archive

Project Tags

• project-x, research-2025, thesis

Advanced Tag Usage

Combining Multiple Tags

Using multiple tags together creates a powerful organization system:

• A GitHub repository might have tags: github, code, golang, project-x
• A YouTube tutorial might have tags: youtube, video, tutorial, programming

This allows for very specific filtering like "show me all programming tutorials that are videos."

Tagging in Hooks

You can use event hooks to automatically add tags based on content:

#!/bin/bash
# Example of a post_download hook that adds tags based on content type

# Get job data from stdin
json_data=$(cat)

# Extract the URL and media type
url=$(echo "$json_data" | jq -r '.url')
media_type=$(echo "$json_data" | jq -r '.media_type')
job_id=$(echo "$json_data" | jq -r '.id')

# Add appropriate tag based on URL pattern
if [[ "$url" == *"github.com"* ]]; then
  curl -X POST -H "Content-Type: application/json" \
    -d '{"tag":"github"}' \
    "http://localhost:8060/api/jobs/$job_id/tags"
fi

# Add language tag based on repository content
if [[ "$media_type" == "git" ]]; then
  # Check if repository contains Go files
  if [[ -f "$file_path/go.mod" ]]; then
    curl -X POST -H "Content-Type: application/json" \
      -d '{"tag":"golang"}' \
      "http://localhost:8060/api/jobs/$job_id/tags"
  fi
fi

Related Documentation

• Job Management - Learn about managing download jobs
• Event Hooks - Set up automated tagging with hooks
• API Reference - Programmatic tag management