Work with Issue Tags

This page shows sample requests that let you work with tags in YouTrack. We cover the following operations:

GET requests to endpoints related to tags
POST requests to endpoints related to tags
DELETE tag from the system

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.

GET requests for tags

Get a list of tags

Get all tags visible to current user (those which he created and which shared with him).

Sample Request

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

Sample Response

        [
          {
            "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 specific tag

Sample Request

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

Sample Response

        {
          "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 specific tag

To get all issues that have specific tag, let's say the one that we got with the previous call, use:

Sample Request

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

Sample Response

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

Read tags of specific issue

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

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

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

Sample Request

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

Sample Response

          {
            "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 user, use:

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

Sample Request

          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 perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7'
        

Sample Response

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

Create 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

        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 perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N' \
        -H 'Content-Type: application/json' \
        -d '{
        "name":"Regression"
        }'
      

Sample Response

        {
          "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's owner will be the user whose permanent token was used when requesting
By default, visibleFor and updateableBy are set to null, which means that only the tag's owner can see and update it.

Update specific tag

To update a specific tag (share, attach to several issues, and so on), use:

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

Sample Request

        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 perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N' \
        -d '{
        "issues":[{"id":"2-60"}],
        "visibleFor":{ "id":"3-0", "$type":"UserGroup" }
        }'
      

Use the following URIs to choose users and groups to share 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

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

Create new issue and tag it

To create a new issue and mark it with an existing tag, send a POST request /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

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

To get project id, use Get projects request with query parameter:

GET /youtrack/api/admin/projects?fields=id&query={project name or short name}
To get tag id, use GET tags request with the query parameter:

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

Sample Response

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

DELETE request for tags

To delete a specific tag from the system, you need to send DELETE request to the specific tag endpoint: /api/tags/{tagID}.

Sample Request

      curl -X DELETE 'https://example.youtrack.cloud/api/tags/6-14' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N'
    

To check that the tag was indeed deleted from the system, send the 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 perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N'
    

In response to this, server should return the following error in the response body:

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

Last modified: 7 November 2024