# Zapini API — Tags

**Version:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Authentication

All endpoints require a Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Generate API tokens in your admin panel under **API Docs → Manage Tokens**.

---

## Tags

Manage conversation tags for organizing and categorizing chats. Tags are tenant-scoped and can be assigned to multiple conversations.

### GET /tags

List all tags for the current tenant.

**Response:**

```json
{
  "success": true,
  "data": {
    "tags": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "VIP",
        "color": "#f59e0b",
        "conversations_count": 15,
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:30:00Z"
      }
    ]
  }
}
```

---

### POST /tags

Create a new tag.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | Tag name (max 50 characters, unique per tenant) |
| color | string | Yes | Hex color code (#RRGGBB) |

**Example:**

```bash
curl -X POST https://zapini.app/api/v1/tags \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Important",
    "color": "#ef4444"
  }'
```

**Response:**

```json
{
  "success": true,
  "message": "Tag created successfully",
  "data": {
    "tag": {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Important",
      "color": "#ef4444",
      "conversations_count": 0,
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z"
    }
  }
}
```

---

### GET /tags/{uuid}

Returns tag details.

---

### PATCH /tags/{uuid}

Update an existing tag.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | No | New tag name (max 50 characters) |
| color | string | No | New hex color code (#RRGGBB) |

---

### DELETE /tags/{uuid}

Delete a tag. The tag will be automatically removed from all conversations.

---

### PUT /conversations/{uuid}/tags

Update tags assigned to a conversation. This replaces all existing tags with the provided list.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| tag_ids | array | Yes | Array of tag UUIDs to assign |

**Example:**

```bash
curl -X PUT https://zapini.app/api/v1/conversations/550e8400-e29b-41d4-a716-446655440045/tags \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"]
  }'
```

**Response:**

```json
{
  "success": true,
  "message": "Conversation tags updated",
  "data": {
    "tags": [
      {"id": "550e8400-e29b-41d4-a716-446655440001", "name": "VIP", "color": "#f59e0b"},
      {"id": "550e8400-e29b-41d4-a716-446655440002", "name": "Support", "color": "#3b82f6"}
    ]
  }
}
```

**Note:** To remove all tags from a conversation, send an empty array: `{"tag_ids": []}`

> **Breaking Change v1.2.0:** Tag IDs are now UUIDs instead of integers.

---

*Generated by Zapini — https://zapini.app*