Work with Issue Tags

This page shows sample requests that let you work with tags in YouTrack.

Summary

Use the tag endpoints to read tags, create and update tags, and delete tags from YouTrack.

GET requests to endpoints related to tags
POST requests to endpoints related to tags
DELETE requests to endpoints related to tags

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, 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 visibleFor and updateableBy 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 read, create, update, and delete issue tags with the YouTrack REST API.

GET Requests for Tags

Use GET requests to read tags, inspect tag details, and find issues or users associated with tags.

Get a List of Tags

Get all tags that are visible to the current user, including tags they created and tags that are shared with them.

Sample Request

The following request shows the API call for this operation.

          curl -X GET \
          'https://example.youtrack.cloud/api/tags?fields=id,name,owner(id,name),visibleFor(id,name),updateableBy(id,name),issues(id,idReadable,summary),untagOnResolve&$top=2&$skip=0' \
          -H 'Accept: application/json' \
          -H 'Authorization: Bearer <YouTrack_token>'
      

Sample Response

If the request is successful, the response contains data similar to the following sample.

          [
              {
                  "issues": [],
                  "untagOnResolve": false,
                  "owner": {
                      "name": "John Doe",
                      "id": "1-2",
                      "$type": "User"
                  },
                  "visibleFor": null,
                  "updateableBy": null,
                  "name": "Star",
                  "id": "6-1",
                  "$type": "IssueTag"
              },
              {
                  "issues": [
                      {
                          "summary": "Example for Get all tags visible to current user",
                          "idReadable": "RAP-1",
                          "id": "2-60",
                          "$type": "Issue"
                      },
                      {
                          "summary": "Example for Get specific issue tag",
                          "idReadable": "RAP-2",
                          "id": "2-62",
                          "$type": "Issue"
                      }
                  ],
                  "untagOnResolve": false,
                  "owner": {
                      "name": "John Doe",
                      "id": "1-2",
                      "$type": "User"
                  },
                  "visibleFor": {
                      "name": "All Users",
                      "id": "3-0",
                      "$type": "UserGroup"
                  },
                  "updateableBy": {
                      "name": "All Users",
                      "id": "3-0",
                      "$type": "UserGroup"
                  },
                  "name": "GET",
                  "id": "6-4",
                  "$type": "IssueTag"
              }
          ]
      

Get a Specific Tag

Use the tag ID to request details for a specific tag.

Sample Request

The following request shows the API call for this operation.

          curl -L -X GET 'https://example.youtrack.cloud/api/tags/6-4?fields=id,name,owner(login,name),visibleFor(name,id),issues(idReadable,summary)' \
          -H 'Accept: application/json' \
          -H 'Authorization: Bearer <YouTrack_token>'
      

Sample Response

If the request is successful, the response contains data similar to the following sample.

          {
              "issues": [
                  {
                      "idReadable": "SP-45",
                      "summary": "REST API lets you create issues!",
                      "$type": "Issue"
                  },
                  {
                      "idReadable": "RAP-2",
                      "summary": "Example for Get specific issue tag",
                      "$type": "Issue"
                  },
                  {
                      "idReadable": "RAP-4",
                      "summary": "New issue with new tag",
                      "$type": "Issue"
                  }
              ],
              "owner": {
                  "login": "john.doe",
                  "name": "John Doe",
                  "$type": "User"
              },
              "visibleFor": {
                  "name": "All Users",
                  "id": "3-0",
                  "$type": "UserGroup"
              },
              "name": "GET",
              "id": "6-4",
              "$type": "IssueTag"
          }
      

Read a List of Issues with a Specific Tag

To get all issues that have a specific tag, use:

Sample Request

The following request shows the API call for this operation.

          curl -X GET \
          'https://example.youtrack.cloud/api/tags/6-4/issues?fields=id,idReadable,summary&$top=2' \
          -H 'Accept: application/json' \
          -H 'Authorization: Bearer <YouTrack_token>'
      

Sample Response

If the request is successful, the response contains data similar to the following sample.

          [
              {
                  "idReadable": "SP-45",
                  "summary": "REST API lets you create issues!",
                  "id": "2-50",
                  "$type": "Issue"
              },
              {
                  "idReadable": "RAP-2",
                  "summary": "Example for Get specific issue tag",
                  "id": "2-62",
                  "$type": "Issue"
              },
              {
                  "idReadable": "RAP-4",
                  "summary": "New issue with new tag",
                  "id": "2-66",
                  "$type": "Issue"
              }
          ]
      

Read Existing Tags Through Other Resources

You can also read tag data from issue and user resources.

Read Tags of a Specific Issue

To get the list of tags that are attached to a specific issue, use one of these requests:

GET /api/issues/{issueID}?fields=tags()

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

Sample Request

The following request shows the API call for this operation.

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

Sample Response

If the request is successful, the response contains data similar to the following sample.

            {
              "tags":[
                {
                  "name":"GET",
                  "id":"6-4",
                  "$type":"IssueTag"
                },
                {
                  "name":"issueTags resource",
                  "id":"6-6",
                  "$type":"IssueTag"
                },
                {
                  "name":"must have",
                  "id":"6-7",
                  "$type":"IssueTag"
                }
              ],
              "$type":"Issue"
            }
        

Read Tags That Belong to a User

To get the list of tags that belong to a user, use:

GET /api/users/{userID}?fields=tags()

Sample Request

The following request shows the API call for this operation.

            curl -L -X GET 'https://example.youtrack.cloud/api/users/1-2?fields=tags(id,name,owner(name)),name,login' \
            -H 'Accept: application/json' \
            -H 'Authorization: Bearer <YouTrack_token>'
        

Sample Response

If the request is successful, the response contains data similar to the following sample.

            {
              "tags":[
                {
                  "owner":{
                    "name":"John Doe",
                    "$type":"User"
                  },
                  "name":"Star",
                  "id":"6-1",
                  "$type":"IssueTag"
                },
                {
                  "owner":{
                    "name":"John Doe",
                    "$type":"User"
                  },
                  "name":"GET",
                  "id":"6-4",
                  "$type":"IssueTag"
                },
                {
                  "owner":{
                    "name":"John Doe",
                    "$type":"User"
                  },
                  "name":"issueTags resource",
                  "id":"6-6",
                  "$type":"IssueTag"
                }
              ],
              "login": "john.doe",
              "name": "John Doe",
              "$type":"User"
            }
        

POST Requests for Tags

Use POST requests to create tags, update tag attributes, and add tags when creating issues.

Create a New Tag

To create a new tag, use the POST request to the /api/tags endpoint. To create a tag, you must provide at least the name attribute.

Sample Request

The following request shows the API call for this operation.

          curl -X POST \
          'https://example.youtrack.cloud/api/tags?fields=id,name,owner(id,name),visibleFor(id,name),updateableBy(id,name),issues(id),untagOnResolve' \
          -H 'Accept: application/json' \
          -H 'Authorization: Bearer <YouTrack_token>' \
          -H 'Content-Type: application/json' \
          -d '{
          "name":"Regression"
          }'
      

Sample Response

If the request is successful, the response contains data similar to the following sample.

          {
            "issues":[],
            "untagOnResolve":false,
            "owner":{
              "name":"John Doe",
              "id":"1-2",
              "$type":"User"
            },
            "visibleFor":null,
            "updateableBy":null,
            "name":"Regression",
            "id":"6-11",
            "$type":"IssueTag"
          }
      

The tag owner is the user whose permanent token is used to send the request.
By default, visibleFor and updateableBy are set to null, which means that only the tag's owner can see and update it.

Update a Specific Tag

To update a specific tag, for example to share it or attach it to several issues, use:

POST /api/tags/{tagID}?{fields}

Sample Request

The following request shows the API call for this operation.

          curl -X POST \
          'https://example.youtrack.cloud/api/tags/6-11?fields=id,name,visibleFor(id),issues(id)' \
          -H 'Accept: application/json' \
          -H 'Authorization: Bearer <YouTrack_token>' \
          -d '{
          "issues":[{"id":"2-60"}],
          "visibleFor":{ "id":"3-0", "$type":"UserGroup" }
          }'
      

Use the following URIs to choose users and groups to share the tag with:

GET /youtrack/api/groups?fields=id,name
GET /youtrack/api/users?fields=id,name
GET /youtrack/api/issues?fields=id,summary&query=project:+RAP

Sample Response

If the request is successful, the response contains data similar to the following sample.

          {
            "issues":[
              {
                "id":"2-60",
                "$type":"Issue"
              }
            ],
            "visibleFor":{"id":"3-0","$type":"UserGroup"},
            "name":"Regression",
            "id":"6-11",
            "$type":"IssueTag"
          }
      

Create a New Issue and Tag It

To create a new issue and mark it with an existing tag, send a POST request to the /api/issues endpoint, and provide at least the following attributes in the request payload:

project: id or name of the project where you want to create the issue.
summary: issue summary.
tags: one or more tags to add to the issue.

Sample Request

The following request shows the API call for this operation.

          curl -X POST \
          'https://example.youtrack.cloud/api/issues?fields=id,summary,tags(id,name)' \
          -H 'Accept: application/json' \
          -H 'Authorization: Bearer <YouTrack_token>' \
          -H 'Content-Type: application/json' \
          -d '{
          “project": { “id":"0-2" },
          “summary": “New issue with existing tag",
          “tags": [ { “id": “6-11" } ]
          }'
      

To get the project ID, see Get a Project ID.
To get the tag ID, use a GET tags request with the query parameter:
GET /youtrack/api/tags?fields=id&query={tag name}

Sample Response

If the request is successful, the response contains data similar to the following sample.

          {
            "summary":"New issue with existing tag",
            "tags":[
              {
                "name":"Regression",
                "id":"6-11",
                "$type":"IssueTag"
              }
            ],
            "id":"2-66",
            "$type":"Issue"
          }
      

DELETE Requests for Tags

Use DELETE requests to remove tags from YouTrack.

To delete a tag:

Send a DELETE request to the specific tag endpoint:
/api/tags/{tagID}
curl -X DELETE 'https://example.youtrack.cloud/api/tags/6-14' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'
To check that the tag was deleted from the system, send a GET request to the same URI of the deleted tag:
curl -X GET 'https://example.youtrack.cloud/api/tags/6-14' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <YouTrack_token>'

In response, the server returns the following error in the response body:

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

18 August 2026