---
schema: rendered-html/v1
title: "Tag or Untag Issues | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/api-usecase-add-remove-tags.html
generated_at: 2026-06-11T15:00:50.377272+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](jetbrains__com__help__youtrack__devportal__api-use-cases.md)
- 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
- Update Issue Custom Fields
- Update a Text Field Value
- Clear Values of Custom Fields
- Apply Commands to Issues
- [Tag or Untag Issues](api-usecase-add-remove-tags.html)
- Work with Issue Tags
- Attach Files to an Issue
- Delete an Issue Attachment
- Download an Issue Attachment
- Link Issues
- Get Issue History
- Get a Database Backup
- [Add User to Project Team](jetbrains__com__help__youtrack__devportal__api-usecase-add-user-to-team.md)
- [REST API Troubleshooting](jetbrains__com__help__youtrack__devportal__api-troubleshooting.md)
- Color Indices List
- Hub REST API

1. YouTrack REST API
2. [REST API Use Cases](jetbrains__com__help__youtrack__devportal__api-use-cases.md)
3. [Tag or Untag Issues](#0)

# Tag or Untag Issues﻿

Last modified: 07 May 2026

## Use Case﻿

Use YouTrack REST API to add or remove issue tags.

## Summary﻿

Let's say you have an application that can integrate with YouTrack. For example, a build server. And you would like to tag an issue that is mentioned in a commit, when the build containing this change is successful.

You can implement such logic with the help of REST API in YouTrack. You will need to know the following details:

- The database ID of the issue that you wish to tag or its human-readable ID.
- The database ID of the tag.

To send a request to add a specific tag to an issue, use dedicated resources for tags. These requests are covered on this page.

You can also use the `/api/commands` REST API resource. For details, take a look at the Apply Commands to Issues page.

## 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**, and **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 sharing settings of a tag: the `readSharingSettings`, `tagSharingSettings`, and `updateSharingSettings` 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 actual procedure to tag an issue is pretty straightforward and short. Note that we assume that you already know the ID of the target issue.

### Tag an Issue﻿

### To tag an issue:﻿

1. Read the list of all tags that are owned by or shared with the current user. Use the /api/tags endpoint:

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

   If you know the name of the tag that you wish to add to the target issue, you can narrow the returned results by using the `query` request parameter:

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

   For our use case, the `fields` request parameter should contain at least `id` and `name` attributes. For example:

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

   In response, the server would return the following data:

   [
     {
       "name": "Star",
       "id": "6-1",
       "$type": "Tag"
     },
     {
       "name": "To deploy",
       "id": "6-4",
       "$type": "Tag"
     }
   ]

   Let's use the `To deploy` tag. Its database id is `6-4`.
2. Now let's add the tag to the target issue. To do so, we need to send a POST request to the /api/issues/{issueID}/tags endpoint and in the request payload, we must provide the ID of the tag to add to the issue.

   Small reminder: you can identify the issue by either its database or human-readable ID, but you can only identify a tag by its database ID.

   Let's say that the human-readable issue ID mentioned in a commit comment is `SP-3967`. Then the minimal sample request to tag this issue would look as follows:

   curl -X POST 'https://example.youtrack.cloud/api/issues/SP-3967/tags?fields=id,name' \
   -H 'Accept: application/json' \
   -H 'Authorization: Bearer perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N' \
   -H 'Content-Type: application/json' \
   --data-raw '{"id": “6-4"}'

### Untag an Issue﻿

To remove one or more (or all tags, for that matter) from an issue, you need to use the same endpoint: /api/issues/{issueID}/tags?{fields}. The following samples show how you can do it.

#### Remove a Specific Tag﻿

To remove one specific tag from an issue, use the DELETE request to this particular tag's URI: `/api/issues/{issueID}/tags/{tagID}`. For example:

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

To check if the request indeed removed the tag, you can send a GET request to the same tag's URI:

curl -X GET 'https://example.youtrack.cloud/api/issues/SP-3967/tags/6-4' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N'

If the tag was indeed removed, you should get a "Not Found" response, like this:

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

#### Remove All Tags from an Issue﻿

When it comes to a bulk operation, like removing all tags from the issue, you should use POST request to the issue endpoint, and provide empty collection of tags in the request payload. For example:

curl -X POST 'https://example.youtrack.cloud/api/issues/SP-3967?fields=tags(id,name)' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.Rm9yIFRhZ3MgZG9jcw==.kLKXRCjCFTY7OZRiukEFU62VfcwT1N' \
-H 'Content-Type: application/json' \
-d '{
“tags": []
}'

In this request, we also provided `fields=tags(id,name)` parameter to check that we indeed removed all the tags. If the request was successful, we'll see a response body like this:

{
  "tags": [],
  "$type": "Issue"
}

That's it! Happy developing!

- [Tag or Untag Issues](/help/youtrack/devportal/api-usecase-add-remove-tags.html)
- [Use Case](/help/youtrack/devportal/api-usecase-add-remove-tags.html#use-case)
- [Summary](/help/youtrack/devportal/api-usecase-add-remove-tags.html#summary)
- [Permissions](/help/youtrack/devportal/api-usecase-add-remove-tags.html#permissions)
- [Step-by-Step](/help/youtrack/devportal/api-usecase-add-remove-tags.html#step-by-step)

Apply Commands to IssuesWork with Issue Tags

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

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

![](https://bat.bing.com/action/0?ti=5220035&tm=gtm002&Ver=2&mid=b9435a8e-a2a6-44a5-9214-235894b7f5ca&bo=4&sid=452929b065a111f19a7fe7356f74a419&vid=aa3122f0648711f1a10d6d095e10fd87&vids=0&msclkid=N&pi=918639831&lg=en-US&sw=1920&sh=1080&sc=24&tl=Tag%20or%20Untag%20Issues%20%7C%20Developer%20Portal%20for%20YouTrack%20and%20Hub%20Documentation&p=https%3A%2F%2Fwww.jetbrains.com%2Fhelp%2Fyoutrack%2Fdevportal%2Fapi-usecase-add-remove-tags.html&r=&lt=888&pt=1781190048432,30,30,,,3,3,3,3,3,,4,25,26,33,329,329,329,886,888,888&pn=0,0&evt=pageLoad&sv=2&asc=G&cdb=AQAS&rn=549946)
