---
url: https://next.zammad.org/en/reference/rest-api/tags.md
---

# Tags

## Ticket scope

### List

Required permission: `ticket.agent` **or** `admin.tag`

`GET`-Request sent: `/api/v1/tags?object=Ticket&o_id={ticket id}`

::: details

```json
// HTTP-Code 200 OK

{
  "tags": [
    "order",
    "complaint"
  ]
}

```

:::

### Add

Required permission: `ticket.agent` **or** `admin.tag`

`POST`-Request sent: `/api/v1/tags/add`

::::: details

:::: tabs key:reqres

\=== Request

```json
{
  "item": "{tag name}",
  "object": "Ticket",
  "o_id": "{ticket id}"
}

```

::: info
This will create the tag if it doesn't exist and the user has permission
to do so.
:::

\=== Response

```json
// HTTP-Code 201 Created

true

```

::::
:::::

### Remove

Required permission: `ticket.agent` **or** `admin.tag`

`DELETE`-Request sent: `/api/v1/tags/remove`

:::: details

::: tabs key:reqres

\=== Request

```json
{
  "item": "{tag name}",
  "object": "Ticket",
  "o_id": "{ticket id}"
}

```

\=== Response

```json
// HTTP-Code 200 OK

true

```

:::
::::

## Administration scope

### Admin - list

Required permission: `admin.tag`

`GET`-Request sent: `/api/v1/tag_list`

::: details

```json
// HTTP-Code 200 OK

[
  {
    "id": 1,
    "name": "order",
    "count": 0
  },
  {
    "id": 2,
    "name": "complaint",
    "count": 0
  },
  {
    "id": 3,
    "name": "printer problem",
    "count": 0
  }
]

```

:::

### Admin - create

Required permission: `admin.tag`

`POST`-Request sent: `/api/v1/tag_list`

:::: details

::: tabs key:reqres

\=== Request

```json
{
  "name": "tag 5"
}

```

\=== Response

```json
// HTTP-Code 200 OK

{}

```

:::
::::

### Admin - rename

Required permission: `admin.tag`

`PUT`-Request sent: `/api/v1/tag_list/{tag id}`

:::: details

::: tabs key:reqres

\=== Request

```json
{
  "name": "order"
}

```

\=== Response

```json
// HTTP-Code 200 OK

{}

```

:::
::::

### Admin - delete

Required permission: `admin.tag`

`DELETE`-Request sent: `/api/v1/tag_list/{tag id}`

::: details

Response:

```json
// HTTP-Code 200 OK

{}

```

:::