# Tags

### Create a tag <a href="#create-a-tag" id="create-a-tag"></a>

Create a new tag for organizing your audience.

**Endpoint:** `POST /v3/tags`

**Request body:**

| Field   | Type   | Required | Description                         |
| ------- | ------ | -------- | ----------------------------------- |
| `name`  | string | Yes      | Tag name (must be unique per clone) |
| `color` | string | No       | Tag color (defaults to `"default"`) |

**Example request:**

```bash
curl -X POST https://api.delphi.ai/v3/tags \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"name": "VIP", "color": "blue"}'
```

**Example response:**

```json
{
  "id": "tag-001",
  "name": "VIP",
  "color": "blue",
  "created_at": "2025-06-15T10:00:00.000Z",
  "updated_at": "2025-06-15T10:00:00.000Z"
}
```

> Returns `409` if a tag with the same name already exists.

## List all tags

Retrieve all tags for your clone.

**Endpoint:** `GET /v3/tags`

**Example request:**

```bash
curl "https://api.delphi.ai/v3/tags" \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json
{
  "tags": [
    {
      "id": "tag-001",
      "name": "VIP",
      "color": "blue",
      "created_at": "2025-06-15T10:00:00.000Z",
      "updated_at": "2025-06-15T10:00:00.000Z"
    },
    {
      "id": "tag-002",
      "name": "Free Trial",
      "color": "default",
      "created_at": "2025-06-14T08:00:00.000Z",
      "updated_at": "2025-06-14T08:00:00.000Z"
    }
  ],
  "total_count": 2
}
```

> Tags are sorted by newest first.

## Tag a user

Apply a tag to a user in your audience.

**Endpoint:** `POST /v3/users/{user_id}/tags/{tag_name}`

**Path parameters:**

| Parameter  | Type   | Description      |
| ---------- | ------ | ---------------- |
| `user_id`  | string | UUID of the user |
| `tag_name` | string | Exact tag name   |

**Example request:**

```bash
curl -X POST "https://api.delphi.ai/v3/users/u-123/tags/VIP" \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json
{
  "success": true,
  "tag_id": "tag-001",
  "tag_name": "VIP",
  "user_id": "u-123",
  "message": "Tag applied successfully"
}
```

> This operation is idempotent — tagging a user who already has the tag will succeed without error.

## Untag a user

Remove a tag from a user.

**Endpoint:** `DELETE /v3/users/{user_id}/tags/{tag_name}`

**Path parameters:**

| Parameter  | Type   | Description      |
| ---------- | ------ | ---------------- |
| `user_id`  | string | UUID of the user |
| `tag_name` | string | Exact tag name   |

**Example request:**

```bash
curl -X DELETE "https://api.delphi.ai/v3/users/u-123/tags/VIP" \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json
{
  "success": true,
  "tag_id": "tag-001",
  "tag_name": "VIP",
  "user_id": "u-123",
  "message": "Tag removed successfully"
}
```

> This operation is idempotent — untagging a user who doesn't have the tag will succeed without error.