Work item tags
TFS 2017 | TFS 2015 | TFS 2013
Note
Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.
api-version = 1.0
If you haven't already, look at the information on getting started with these APIs.
Get a list of tags
GET https://{instance}/DefaultCollection/_apis/tagging/scopes/{scope}/tags?api-version={version}[&includeInactive={bool}]
| Parameter | Type | Default | Notes |
|---|---|---|---|
| URL | |||
| instance | string | TFS server name ({server:port}). | |
| scope | GUID | ID of the enclosing scope. Typically, this is the ID if the project. You can define your own scope GUIDs, but tags using this scope would not appear in the work item tracking user interface. |
|
| Query | |||
| api-version | string | Version of the API to use. | |
| includeInactive | bool | false | If true, inactive tags are returned. Inactive tags are typically retained for work item history and would not normally be shown to the user. |
Sample request
GET https://mytfsserver/DefaultCollection/_apis/tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags?api-version=1.0
Sample response
{
"count": 9,
"value": [
{
"id": "d3b448f5-01ea-4e04-a779-923160a05111",
"name": "Billing",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/d3b448f5-01ea-4e04-a779-923160a05111"
},
{
"id": "e4b2b4cc-c728-42fa-92d7-1e8187dcdaf1",
"name": "Customer",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/e4b2b4cc-c728-42fa-92d7-1e8187dcdaf1"
},
{
"id": "afb5078a-b81a-4f5d-a7a0-38de6a055200",
"name": "Customer Service",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/afb5078a-b81a-4f5d-a7a0-38de6a055200"
},
{
"id": "9dfc2f21-b2aa-4e11-a36a-f3761e9861cb",
"name": "My Tag",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb"
},
{
"id": "7339639a-089f-4592-b352-993f0648c877",
"name": "Tag1",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/7339639a-089f-4592-b352-993f0648c877"
},
{
"id": "05d4d487-054e-498e-8d6f-9132ed72c295",
"name": "Tag2",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/05d4d487-054e-498e-8d6f-9132ed72c295"
},
{
"id": "d894c59f-9d24-4cce-9242-515f210eb681",
"name": "Technician",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/d894c59f-9d24-4cce-9242-515f210eb681"
},
{
"id": "ec448db2-46bc-49a1-a806-54798dde05b3",
"name": "UX review needed",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/ec448db2-46bc-49a1-a806-54798dde05b3"
},
{
"id": "8b3d3191-bc8f-46b4-ad68-35dd14d1f494",
"name": "zendesk",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/8b3d3191-bc8f-46b4-ad68-35dd14d1f494"
}
]
}
Sample code
Including inactive tags
Sample request
GET https://mytfsserver/DefaultCollection/_apis/tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags?includeInactive=true&api-version=1.0
Sample response
{
"count": 12,
"value": [
{
"id": "d3b448f5-01ea-4e04-a779-923160a05111",
"name": "Billing",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/d3b448f5-01ea-4e04-a779-923160a05111"
},
{
"id": "e4b2b4cc-c728-42fa-92d7-1e8187dcdaf1",
"name": "Customer",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/e4b2b4cc-c728-42fa-92d7-1e8187dcdaf1"
},
{
"id": "afb5078a-b81a-4f5d-a7a0-38de6a055200",
"name": "Customer Service",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/afb5078a-b81a-4f5d-a7a0-38de6a055200"
},
{
"id": "9dfc2f21-b2aa-4e11-a36a-f3761e9861cb",
"name": "My Tag",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb"
},
{
"id": "082d7579-65ae-4401-8768-f11caf29653b",
"name": "New tag",
"active": false,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/082d7579-65ae-4401-8768-f11caf29653b"
},
{
"id": "4cc38671-cbaa-47e3-b5a4-8b6c36edfca8",
"name": "Tag now inactive",
"active": false,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/4cc38671-cbaa-47e3-b5a4-8b6c36edfca8"
},
{
"id": "7339639a-089f-4592-b352-993f0648c877",
"name": "Tag1",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/7339639a-089f-4592-b352-993f0648c877"
},
{
"id": "05d4d487-054e-498e-8d6f-9132ed72c295",
"name": "Tag2",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/05d4d487-054e-498e-8d6f-9132ed72c295"
},
{
"id": "d894c59f-9d24-4cce-9242-515f210eb681",
"name": "Technician",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/d894c59f-9d24-4cce-9242-515f210eb681"
},
{
"id": "3ebd34d1-1796-4f46-8aa4-f430c612ae7f",
"name": "Urgent",
"active": false,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/3ebd34d1-1796-4f46-8aa4-f430c612ae7f"
},
{
"id": "ec448db2-46bc-49a1-a806-54798dde05b3",
"name": "UX review needed",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/ec448db2-46bc-49a1-a806-54798dde05b3"
},
{
"id": "8b3d3191-bc8f-46b4-ad68-35dd14d1f494",
"name": "zendesk",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/8b3d3191-bc8f-46b4-ad68-35dd14d1f494"
}
]
}
Sample code
Get a tag
GET https://{instance}/DefaultCollection/_apis/tagging/scopes/{scope}/tags/{tag}?api-version={version}
| Parameter | Type | Notes |
|---|---|---|
| URL | ||
| instance | string | TFS server name ({server:port}). |
| scope | GUID | ID of the enclosing scope. Typically, this is the ID if the project. You can define your own scope GUIDs, but tags using this scope would not appear in the work item tracking user interface. |
| tag | string | ID or name of the tag. Use ID for durable links to the tag because the name can change. |
| Query | ||
| api-version | string | Version of the API to use. |
By name
Sample request
GET https://mytfsserver/DefaultCollection/_apis/tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/My%20Tag?api-version=1.0
Sample response
{
"id": "9dfc2f21-b2aa-4e11-a36a-f3761e9861cb",
"name": "My Tag",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb"
}
Sample code
By ID
Sample request
GET https://mytfsserver/DefaultCollection/_apis/tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb?api-version=1.0
Sample response
{
"id": "9dfc2f21-b2aa-4e11-a36a-f3761e9861cb",
"name": "My Tag",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb"
}
Sample code
Create a tag
POST https://{instance}/DefaultCollection/_apis/tagging/scopes/{scope}/tags?api-version={version}
Content-type: Application/json
{
"name": { string }
}
| Parameter | Type | Notes |
|---|---|---|
| URL | ||
| instance | string | TFS server name ({server:port}). |
| scope | GUID | ID of the enclosing scope. Typically, this is the ID if the project. You can define your own scope GUIDs, but tags using this scope would not appear in the work item tracking user interface. If the scope does not exist, a new scope will be created and used. To verify that the scope ID represents a project, check for the existence of the project by that ID. |
| Query | ||
| api-version | string | Version of the API to use. |
| Request body | ||
| name | string | Name of the tag. If a tag by that name already exists, no tag is created. Instead, the response body includes the existing tag with that name. |
Sample request
POST https://mytfsserver/DefaultCollection/_apis/tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags?api-version=1.0
{
"name": "My Tag"
}
Sample response
{
"id": "9dfc2f21-b2aa-4e11-a36a-f3761e9861cb",
"name": "My Tag",
"active": true,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb"
}
Sample code
Update a tag
PATCH https://{instance}/DefaultCollection/_apis/tagging/scopes/{scope}/tags/{tag}?api-version={version}
Content-type: Application/json
{
"name": { string },
"active": { bool }
}
| Parameter | Type | Notes |
|---|---|---|
| URL | ||
| instance | string | TFS server name ({server:port}). |
| scope | GUID | ID of the enclosing scope. Typically, this is the ID if the project. You can define your own scope GUIDs, but tags using this scope would not appear in the work item tracking user interface. If the scope does not exist, a new scope will be created and used. To verify that the scope ID represents a project, check for the existence of the project by that ID. |
| tag | string | ID or name of the tag to update. |
| Query | ||
| api-version | string | Version of the API to use. |
| Body | ||
| name | string | New name of the tag. If a tag already exists with this name, in the same scope, the update will fail. Names are not case-sensitive. You can update the name to change the case (from "case" to "Case", for example). |
| active | bool | If false, the tag is inactive and is generally not shown to the user. Inactive tags aren't shown in the VSTS pages, for example. |
Sample request
PATCH https://mytfsserver/DefaultCollection/_apis/tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb?api-version=1.0
{
"name": "My Tag Renamed",
"active": false
}
Sample response
{
"id": "9dfc2f21-b2aa-4e11-a36a-f3761e9861cb",
"name": "My Tag Renamed",
"active": false,
"url": "https://mytfsserver/DefaultCollection/_apis/Tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb"
}
Sample code
Delete a tag
Before you decide to delete a tag, consider that they may be associated with historical revisions of work items or other resources. It is preferable to mark tags as inactive unless you know the tag is not associated with any other resources.
PATCH https://{instance}/DefaultCollection/_apis/tagging/scopes/{scope}/tags/{tag}?api-version={version}
| Parameter | Type | Notes |
|---|---|---|
| URL | ||
| instance | string | TFS server name ({server:port}). |
| scope | GUID | ID of the enclosing scope. Typically, this is the ID if the project. You can define your own scope GUIDs, but tags using this scope would not appear in the work item tracking user interface. |
| tag | string | ID or name of the tag to delete. |
| Query | ||
| api-version | string | Version of the API to use. |
Sample request
DELETE https://mytfsserver/DefaultCollection/_apis/tagging/scopes/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/tags/9dfc2f21-b2aa-4e11-a36a-f3761e9861cb?api-version=1.0