Tag or Untag Issues - Help | Developer Portal for YouTrack and Hub

Use Case

Use YouTrack REST API to add or remove issue tags.

Summary

Let's say you have an application that can integrate with YouTrack. For example, a build server. And you would like to tag an issue that is mentioned in a commit, when the build containing this change is successful.

You can implement such logic with the help of REST API in YouTrack. You will need to know the following details:

The database ID of the issue that you wish to tag or its human-readable ID.
The database ID of the tag.

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

You can also use the /api/commands REST API resource. For details, take a look at the Apply Commands to Issues page.

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 actual procedure to tag an issue is pretty straightforward and short. Note that we assume that you already know the ID of the target issue.

Tag an Issue

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 perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N'

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 perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N' \ -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 perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N'
        

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 perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N'
        

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 perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N' \
          -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"
          }
        