Skip to main content

​
Tags

Tags provide a flexible labeling system for your directory listings. Unlike categories which are hierarchical, tags are flat labels that can be applied to listings for filtering and visual identification. Tags support custom colors and icons for enhanced display.

​
Get Directory Tags

Retrieve all active tags for a specific directory. 
GET /api/directories/{directory_id}/tags
Parameters:
  • directory_id (integer, required): The ID of the directory
Response: 
{
  "data": [
    {
      "id": 1,
      "title": "Open Source",
      "slug": "open-source",
      "is_active": true,
      "icon": null,
      "heroicon": "code-bracket",
      "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",
      "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

Retrieve a specific tag by ID. 
GET /api/directories/{directory_id}/tags/{tag_id}
Parameters:
  • directory_id (integer, required): The ID of the directory
  • tag_id (integer, required): The ID of the tag
Response: 
{
  "data": {
    "id": 1,
    "title": "Open Source",
    "slug": "open-source",
    "is_active": true,
    "icon": null,
    "heroicon": "code-bracket",
    "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

Create a new tag in the directory. 
POST /api/directories/{directory_id}/tags
Parameters:
  • directory_id (integer, required): The ID of the directory
Request Body: 
{
  "title": "New Release",
  "slug": "new-release",
  "is_active": true,
  "heroicon": "sparkles",
  "text_color": "#F59E0B",
  "show_title": true,
  "show_icon": true
}
Request Body Fields:
  • 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
  • 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)
Response: 
{
  "data": {
    "id": 3,
    "title": "New Release",
    "slug": "new-release",
    "is_active": true,
    "icon": null,
    "heroicon": "sparkles",
    "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

Update an existing tag. 
PUT /api/directories/{directory_id}/tags/{tag_id}
Parameters:
  • directory_id (integer, required): The ID of the directory
  • tag_id (integer, required): The ID of the tag
Request Body: 
{
  "title": "Recently Updated",
  "text_color": "#3B82F6",
  "heroicon": "arrow-path"
}
Request Body Fields:
  • 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)
  • 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
Response: 
{
  "data": {
    "id": 3,
    "title": "Recently Updated",
    "slug": "new-release",
    "is_active": true,
    "icon": null,
    "heroicon": "arrow-path",
    "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 a tag from the directory. 
DELETE /api/directories/{directory_id}/tags/{tag_id}
Parameters:
  • directory_id (integer, required): The ID of the directory
  • tag_id (integer, required): The ID of the tag
Response: 
{
  "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

  • text_color sets the accent color for the tag (useful 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