Tags

​

Tags

​

Get Directory Tags

GET /api/directories/{directory_id}/tags

• directory_id (integer, required): The ID of the directory

{
  "data": [
    {
      "id": 1,
      "title": "Open Source",
      "slug": "open-source",
      "is_active": true,
      "icon": null,
      "heroicon": "code-bracket",
      "color": "#EF4444",
      "text_color": "#FFFFFF",
      "show_title": true,
      "show_icon": true,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    },
    {
      "id": 2,
      "title": "Free Tier",
      "slug": "free-tier",
      "is_active": true,
      "icon": null,
      "heroicon": "currency-dollar",
      "color": "#ECFDF5",
      "text_color": "#10B981",
      "show_title": true,
      "show_icon": true,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ]
}

​

Get Single Tag

GET /api/directories/{directory_id}/tags/{tag_id}

• directory_id (integer, required): The ID of the directory
• tag_id (integer, required): The ID of the tag

{
  "data": {
    "id": 1,
    "title": "Open Source",
    "slug": "open-source",
    "is_active": true,
    "icon": null,
    "heroicon": "code-bracket",
    "color": "#EF4444",
    "text_color": "#FFFFFF",
    "show_title": true,
    "show_icon": true,
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

​

Create Tag

POST /api/directories/{directory_id}/tags

• directory_id (integer, required): The ID of the directory

{
  "title": "New Release",
  "slug": "new-release",
  "is_active": true,
  "heroicon": "sparkles",
  "color": "#FEF3C7",
  "text_color": "#F59E0B",
  "show_title": true,
  "show_icon": true
}

• title (string, required): The tag title (max 255 characters)
• slug (string, optional): URL-safe slug (lowercase letters, numbers, hyphens only). Auto-generated from title if not provided
• is_active (boolean, optional): Whether the tag is active (default: true)
• icon (string, optional): Custom uploaded icon path (max 255 characters)
• heroicon (string, optional): Heroicon name to use as the tag icon (max 255 characters). Takes priority over icon when both are set
• color (string, optional): Background color for the tag (max 255 characters, e.g. “#F59E0B”)
• text_color (string, optional): Text/accent color for the tag display (max 255 characters, e.g. “#FF0000”)
• show_title (boolean, optional): Whether to display the tag title (default: true)
• show_icon (boolean, optional): Whether to display the tag icon (default: true)

{
  "data": {
    "id": 3,
    "title": "New Release",
    "slug": "new-release",
    "is_active": true,
    "icon": null,
    "heroicon": "sparkles",
    "color": "#FEF3C7",
    "text_color": "#F59E0B",
    "show_title": true,
    "show_icon": true,
    "created_at": "2024-01-16T09:00:00.000000Z",
    "updated_at": "2024-01-16T09:00:00.000000Z"
  }
}

​

Update Tag

PUT /api/directories/{directory_id}/tags/{tag_id}

• directory_id (integer, required): The ID of the directory
• tag_id (integer, required): The ID of the tag

{
  "title": "Recently Updated",
  "color": "#EFF6FF",
  "text_color": "#3B82F6",
  "heroicon": "arrow-path"
}

• title (string, optional): The tag title (max 255 characters)
• slug (string, optional): URL-safe slug (lowercase letters, numbers, hyphens only)
• is_active (boolean, optional): Whether the tag is active
• icon (string, optional): Custom uploaded icon path (max 255 characters)
• heroicon (string, optional): Heroicon name to use as the tag icon (max 255 characters)
• color (string, optional): Background color for the tag (max 255 characters)
• text_color (string, optional): Text/accent color for the tag display (max 255 characters)
• show_title (boolean, optional): Whether to display the tag title
• show_icon (boolean, optional): Whether to display the tag icon

{
  "data": {
    "id": 3,
    "title": "Recently Updated",
    "slug": "new-release",
    "is_active": true,
    "icon": null,
    "heroicon": "arrow-path",
    "color": "#EFF6FF",
    "text_color": "#3B82F6",
    "show_title": true,
    "show_icon": true,
    "created_at": "2024-01-16T09:00:00.000000Z",
    "updated_at": "2024-01-16T10:15:00.000000Z"
  }
}

​

Delete Tag

DELETE /api/directories/{directory_id}/tags/{tag_id}

• directory_id (integer, required): The ID of the directory
• tag_id (integer, required): The ID of the tag

{
  "message": "Tag deleted successfully"
}

​

Key Features

​

Slug Generation

• Slugs are automatically generated from the tag title if not provided
• Slugs must be URL-safe (lowercase letters, numbers, and hyphens only)

​

Icon Support

• Tags support two types of icons: custom uploaded icons (icon) and Heroicons (heroicon)
• When both are set, heroicon takes priority for display
• Use show_icon to control icon visibility

​

Display Customization

• color sets the tag’s background color and text_color its text/accent color — pair them for color-coded labels
• show_title and show_icon control which parts of the tag are visible
• Combine these options to create icon-only tags, text-only tags, or full tags with both