---
schema: rendered-html/v1
title: "Work with Issue Tags | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/api-usecase-work-with-tags.html
generated_at: 2026-06-11T15:01:33.237237+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Get Started with REST API
- REST API Reference
- REST API Use Cases
- Create an Issue
- Create an Issue and Set Custom Fields
- Get Issues List with All Values
- Get Value for an Issue Custom Field
- [Add Value to a Set](jetbrains__com__help__youtrack__devportal__api-usecase-add-value-to-bundle.md)
- Update Issue Custom Fields
- [Update a Text Field Value](jetbrains__com__help__youtrack__devportal__api-usecase-update-text-field-value.md)
- Clear Values of Custom Fields
- [Apply Commands to Issues](jetbrains__com__help__youtrack__devportal__api-usecase-commands.md)
- Tag or Untag Issues
- [Work with Issue Tags](api-usecase-work-with-tags.html)
- [Attach Files to an Issue](jetbrains__com__help__youtrack__devportal__api-usecase-attach-files.md)
- [Delete an Issue Attachment](jetbrains__com__help__youtrack__devportal__api-usecase-delete-issue-attachment.md)
- [Download an Issue Attachment](jetbrains__com__help__youtrack__devportal__api-usecase-download-issue-attachment.md)
- Link Issues
- [Get Issue History](jetbrains__com__help__youtrack__devportal__api-usecase-issue-history.md)
- [Get a Database Backup](jetbrains__com__help__youtrack__devportal__api-usecase-backup.md)
- Add User to Project Team
- REST API Troubleshooting
- Color Indices List
- Hub REST API

1. YouTrack REST API
2. REST API Use Cases
3. [Work with Issue Tags](#0)

# Work with Issue Tags﻿

Last modified: 07 May 2026

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](/help/youtrack/devportal/api-usecase-work-with-tags.html#read-tags)
- [POST requests to endpoints related to tags](/help/youtrack/devportal/api-usecase-work-with-tags.html#post-requests-for-tags)
- [DELETE tag from the system](/help/youtrack/devportal/api-usecase-work-with-tags.html#delete-request-for-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.

## 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}`.

> ### tip
>
> Required permissions
>
> To 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"
}
```

- [Work with Issue Tags](/help/youtrack/devportal/api-usecase-work-with-tags.html)
- [Permissions](/help/youtrack/devportal/api-usecase-work-with-tags.html#permissions)
- [GET requests for tags](/help/youtrack/devportal/api-usecase-work-with-tags.html#read-tags)
- [POST requests for tags](/help/youtrack/devportal/api-usecase-work-with-tags.html#post-requests-for-tags)
- [DELETE request for tags](/help/youtrack/devportal/api-usecase-work-with-tags.html#delete-request-for-tags)

Tag or Untag Issues[Attach Files to an Issue](jetbrains__com__help__youtrack__devportal__api-usecase-attach-files.md)

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
