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 theApply Commands to Issues 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.

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.

To tag an issue:

Read the list of all tags that are owned by or shared with the current user. Use the /api/tags 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 -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:
[ { "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.
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 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 -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}. 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 -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 -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:

            {
                "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 -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:

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

That's it! Happy developing!

18 August 2026