> ## Documentation Index
> Fetch the complete documentation index at: https://docs.directify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags

> Manage tags for directories through the Directify API - create, read, update, and delete tags with full CRUD operations.

## 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.

```http theme={null}
GET /api/directories/{directory_id}/tags
```

**Parameters:**

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

**Response:**

```json theme={null}
{
  "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

Retrieve a specific tag by ID.

```http theme={null}
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:**

```json theme={null}
{
  "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

Create a new tag in the directory.

```http theme={null}
POST /api/directories/{directory_id}/tags
```

**Parameters:**

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

**Request Body:**

```json theme={null}
{
  "title": "New Release",
  "slug": "new-release",
  "is_active": true,
  "heroicon": "sparkles",
  "color": "#FEF3C7",
  "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
* `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)

**Response:**

```json theme={null}
{
  "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

Update an existing tag.

```http theme={null}
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:**

```json theme={null}
{
  "title": "Recently Updated",
  "color": "#EFF6FF",
  "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)
* `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

**Response:**

```json theme={null}
{
  "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 a tag from the directory.

```http theme={null}
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:**

```json theme={null}
{
  "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