Tags

Management of tags for call categorization. Tags can be organized in a hierarchy (tree). Requires attendant role or above.

Endpoints

Method	Endpoint	Description	Minimum Role
GET	/api/v1/tags	List tags	attendant
POST	/api/v1/tags	Create tag	attendant
GET	/api/v1/tags/:id	Get tag	attendant
PUT	/api/v1/tags/:id	Update tag	attendant
DELETE	/api/v1/tags/:id	Delete tag	supervisor
GET	/api/v1/tags/tree	Hierarchical tag tree	attendant

---

List Tags

GET /api/v1/tags

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	50	Items per page
sort_by	string	name	Sort field
sort_order	string	asc	Sort direction
search	string	-	Filter by name

Request Example

curl -X GET "https://voki.avanter.com.br/api/v1/tags" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": [
    {
      "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Suporte",
      "color": "#3b82f6",
      "parent_id": null,
      "usage_count": 45,
      "inserted_at": "2026-01-10T09:00:00Z"
    },
    {
      "id": "t2b3c4d5-e6f7-8901-bcde-f23456789012",
      "name": "Bug",
      "color": "#ef4444",
      "parent_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "usage_count": 12,
      "inserted_at": "2026-01-10T09:30:00Z"
    },
    {
      "id": "t3c4d5e6-f7a8-9012-cdef-345678901234",
      "name": "Vendas",
      "color": "#22c55e",
      "parent_id": null,
      "usage_count": 30,
      "inserted_at": "2026-01-10T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 50,
    "total_pages": 1,
    "total_count": 3
  }
}

---

Create Tag

POST /api/v1/tags

Request Body

Field	Type	Required	Description
name	string	Yes	Tag name
color	string	No	Hexadecimal color (default: #6b7280)
parent_id	uuid	No	Parent tag ID (for hierarchy)

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/tags \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "Feature Request",
      "color": "#8b5cf6",
      "parent_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890"
    }
  }'

Success Response (201)

{
  "data": {
    "id": "t4d5e6f7-a8b9-0123-defg-456789012345",
    "name": "Feature Request",
    "color": "#8b5cf6",
    "parent_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "usage_count": 0,
    "inserted_at": "2026-02-18T17:00:00Z"
  }
}

---

Get Tag

GET /api/v1/tags/:id

---

Update Tag

PUT /api/v1/tags/:id

Request Example

curl -X PUT https://voki.avanter.com.br/api/v1/tags/t1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "color": "#2563eb"
    }
  }'

---

Delete Tag

DELETE /api/v1/tags/:id

Note

Tags with sub-tags will be deleted in cascade. Tags applied to calls will be dissociated.

Request Example

curl -X DELETE https://voki.avanter.com.br/api/v1/tags/t4d5e6f7-a8b9-0123-defg-456789012345 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (204)

No response body.

---

Tag Tree

Returns tags organized in a hierarchical structure.

GET /api/v1/tags/tree

Request Example

curl -X GET https://voki.avanter.com.br/api/v1/tags/tree \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": [
    {
      "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Suporte",
      "color": "#3b82f6",
      "usage_count": 45,
      "children": [
        {
          "id": "t2b3c4d5-e6f7-8901-bcde-f23456789012",
          "name": "Bug",
          "color": "#ef4444",
          "usage_count": 12,
          "children": []
        },
        {
          "id": "t4d5e6f7-a8b9-0123-defg-456789012345",
          "name": "Feature Request",
          "color": "#8b5cf6",
          "usage_count": 0,
          "children": []
        }
      ]
    },
    {
      "id": "t3c4d5e6-f7a8-9012-cdef-345678901234",
      "name": "Vendas",
      "color": "#22c55e",
      "usage_count": 30,
      "children": []
    }
  ]
}