Developer Portal for YouTrack and Hub 2021.1 Help

Work with Issue Tags

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

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 or Saved Search.

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 or Saved Search 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.myjetbrains.com/youtrack/api/issueTags?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.myjetbrains.com/youtrack/api/issueTags/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.myjetbrains.com/youtrack/api/issueTags/6-4/issues?fields=id,idReadable,summary&$top=2' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N'

Sample server 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.myjetbrains.com/youtrack/api/issues/2-60?fields=tags(id,name)' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N'

Sample server 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/admin/users/{userID}?fields=tags()

Sample request:

curl -L -X GET 'https://example.myjetbrains.com/youtrack/api/admin/users/1-2?fields=tags(id,name,owner(name)),name,login' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7'

Example server 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/issueTags endpoint. To create a tag, you must provide at least the name attribute.

Sample request:

curl -X POST \ 'https://example.myjetbrains.com/youtrack/api/issueTags?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" }'

Example server 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, etc), use:

Example request:

curl -X POST \ 'https://example.myjetbrains.com/youtrack/api/issueTags/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 URI-s to choose users and groups to share tag with:

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

Example server 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.

Example request:

curl -X POST \ 'https://example.myjetbrains.com/youtrack/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/issueTags?fields=id&query={tag name}

Example server 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/issueTags/{tagID}.

Sample request:

curl -X DELETE 'https://example.myjetbrains.com/youtrack/api/issueTags/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.myjetbrains.com/youtrack/api/issueTags/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: 8 April 2021