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
andupdateableBy
are set tonull
, 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}
.
tip
Required permissionsTo delete a tag, the user account that sends the request must have Delete Tag or Saved Search permission.
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"
}