# Tag or Untag Issues

Use YouTrack REST API to add or remove issue tags. For example, you can tag an issue that is mentioned in a commit when the build containing this change is successful.

You can also use the `/api/commands` REST API resource. For details, take a look at the[Apply Commands to Issues](api-usecase-commands.html) page.

## Summary

To add a specific tag to an issue, send a request to the dedicated tag resources. These requests are covered on this page.

## Before You Start

Before you update tags for an issue, make sure you know the database ID or human-readable ID of the issue that you want to tag. To learn how to get these IDs, see [Get a List of Issues with All Values](api-howto-get-issues-with-all-values.html).

## Permissions

Operations with tags are covered by the following permissions: Create Tag or Saved Search, Delete Tag or Saved Search, Edit Tag or Saved Search, and Share Tag, Saved Search, or Agile Board.

In addition to these permissions that are required to perform the corresponding operation, you need to pay attention to the sharing settings of a tag: the `readSharingSettings`, `tagSharingSettings`, and `updateSharingSettings` attributes of a tag. By default, a tag is created with these parameters set to its owner. To share a tag, the user not only must have Share Tag, Saved Search, or Agile Board permission, but also should set these attributes correctly.

## Step-by-Step

The following sections show how to add a tag to an issue and how to remove tags from an issue. These examples assume that you already know the ID of the target issue.

### Tag an Issue

To add a tag to an issue, get the tag ID, then send a `POST` request to the issue tags endpoint.

Procedure: To tag an issue:

1. Read the list of all tags that are owned by or shared with the current user. Use the [/api/tags](resource-api-tags.html) endpoint:

```
GET /api/tags?{fields}&{$top}&{$skip}
```

If you know the name of the tag that you wish to add to the target issue, you can narrow the returned results by using the `query` request parameter:

```
GET /api/tags?{fields}&query={tag name}
```

For our use case, the `fields` request parameter should contain at least `id` and `name` attributes. For example:

```CURL
curl -X GET 'https://example.youtrack.cloud/api/tags?fields=id,name' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YouTrack_token>'
```

In response, the server would return the following data:

```JSON
[
    {
        "name": "Star",
        "id": "6-1",
        "$type": "Tag"
    },
    {
        "name": "To deploy",
        "id": "6-4",
        "$type": "Tag"
    }
]
```

Let's use the `To deploy` tag. Its database id is `6-4`.

2. Now let's add the tag to the target issue. To do so, we need to send a POST request to the [/api/issues/{issueID}/tags](resource-api-issues-issueID-tags.html) endpoint and in the request payload, we must provide the ID of the tag to add to the issue.

Small reminder: you can identify the issue by either its database or human-readable ID, but you can only identify a tag by its database ID.

Let's say that the human-readable issue ID mentioned in a commit comment is `SP-3967`. Then the minimal sample request to tag this issue would look as follows:

```CURL
curl -X POST 'https://example.youtrack.cloud/api/issues/SP-3967/tags?fields=id,name' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YouTrack_token>' \
-H 'Content-Type: application/json' \
--data-raw '{"id": “6-4"}'
```

### Untag an Issue

To remove one or more (or all tags, for that matter) from an issue, you need to use the same endpoint: [/api/issues/{issueID}/tags?{fields}](operations-api-issues-issueID-tags.html). The following samples show how you can do it.

#### Remove a Specific Tag

To remove one specific tag from an issue, use the DELETE request to this particular tag's URI: `/api/issues/{issueID}/tags/{tagID}`. For example:

```CURL
curl -X DELETE 'https://example.youtrack.cloud/api/issues/SP-3967/tags/6-4' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YouTrack_token>'
```

To check if the request indeed removed the tag, you can send a GET request to the same tag's URI:

```CURL
curl -X GET 'https://example.youtrack.cloud/api/issues/SP-3967/tags/6-4' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YouTrack_token>'
```

If the tag was indeed removed, you should get a "Not Found" response, like this:

```JSON
{
    "error": "Not Found",
    "error_description": "Entity with id 6-4 not found"
}
```

#### Remove All Tags from an Issue

When it comes to a bulk operation, like removing all tags from the issue, you should use POST request to the issue endpoint, and provide empty collection of tags in the request payload. For example:

```CURL
curl -X POST 'https://example.youtrack.cloud/api/issues/SP-3967?fields=tags(id,name)' \
-H 'Authorization: Bearer <YouTrack_token>' \
-H 'Content-Type: application/json' \
-d '{
“tags": []
}'
```

In this request, we also provided `fields=tags(id,name)` parameter to check that we indeed removed all the tags. If the request was successful, we'll see a response body like this:

```JSON
{
    "tags": [],
    "$type": "Issue"
}
```

That's it! Happy developing!