2020-05-27 03:08:26 +00:00
---
stage: Plan
group: Project Management
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
2017-05-10 18:48:07 +00:00
# Labels API
2014-08-12 12:16:25 +00:00
2019-12-30 12:09:15 +00:00
NOTE: **Note:**
2020-02-06 15:09:11 +00:00
The `description_html` - was added to response JSON in [GitLab 12.7 ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413 ).
2019-12-30 12:09:15 +00:00
2014-08-12 12:16:25 +00:00
## List labels
2016-01-18 08:41:42 +00:00
Get all labels for a given project.
2014-08-12 12:16:25 +00:00
2020-05-12 15:10:33 +00:00
By default, this request returns 20 results at a time because the API results [are paginated ](README.md#pagination ).
2020-02-27 09:09:01 +00:00
```plaintext
2014-08-12 12:16:25 +00:00
GET /projects/:id/labels
```
2019-08-06 16:27:46 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2020-02-06 15:09:11 +00:00
| `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false` . _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ |
2019-09-26 18:06:29 +00:00
| `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true` . |
2016-01-18 08:41:42 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/labels?with_counts=true"
2016-01-18 08:41:42 +00:00
```
Example response:
2014-08-12 12:16:25 +00:00
```json
[
2016-11-04 11:52:38 +00:00
{
"id" : 1,
"name" : "bug",
"color" : "#d9534f",
2019-02-12 18:36:45 +00:00
"text_color" : "#FFFFFF",
2016-11-04 11:52:38 +00:00
"description": "Bug reported by user",
2019-12-30 12:09:15 +00:00
"description_html": "Bug reported by user",
2016-11-04 11:52:38 +00:00
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 1,
"subscribed": false,
2019-02-13 21:16:40 +00:00
"priority": 10,
"is_project_label": true
2016-11-04 11:52:38 +00:00
},
{
"id" : 4,
"color" : "#d9534f",
2019-02-12 18:36:45 +00:00
"text_color" : "#FFFFFF",
2016-11-04 11:52:38 +00:00
"name" : "confirmed",
"description": "Confirmed issue",
2019-12-30 12:09:15 +00:00
"description_html": "Confirmed issue",
2016-11-04 11:52:38 +00:00
"open_issues_count": 2,
"closed_issues_count": 5,
"open_merge_requests_count": 0,
"subscribed": false,
2019-02-13 21:16:40 +00:00
"priority": null,
"is_project_label": true
2016-11-04 11:52:38 +00:00
},
{
"id" : 7,
"name" : "critical",
"color" : "#d9534f",
2019-02-12 18:36:45 +00:00
"text_color" : "#FFFFFF",
2016-11-04 11:52:38 +00:00
"description": "Critical issue. Need fix ASAP",
2019-12-30 12:09:15 +00:00
"description_html": "Critical issue. Need fix ASAP",
2016-11-04 11:52:38 +00:00
"open_issues_count": 1,
"closed_issues_count": 3,
"open_merge_requests_count": 1,
"subscribed": false,
2019-02-13 21:16:40 +00:00
"priority": null,
"is_project_label": true
2016-11-04 11:52:38 +00:00
},
{
"id" : 8,
"name" : "documentation",
"color" : "#f0ad4e",
2019-02-12 18:36:45 +00:00
"text_color" : "#FFFFFF",
2016-11-04 11:52:38 +00:00
"description": "Issue about documentation",
2019-12-30 12:09:15 +00:00
"description_html": "Issue about documentation",
2016-11-04 11:52:38 +00:00
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 2,
"subscribed": false,
2019-02-13 21:16:40 +00:00
"priority": null,
"is_project_label": false
2016-11-04 11:52:38 +00:00
},
{
"id" : 9,
"color" : "#5cb85c",
2019-02-12 18:36:45 +00:00
"text_color" : "#FFFFFF",
2016-11-04 11:52:38 +00:00
"name" : "enhancement",
"description": "Enhancement proposal",
2019-12-30 12:09:15 +00:00
"description_html": "Enhancement proposal",
2016-11-04 11:52:38 +00:00
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 1,
"subscribed": true,
2019-02-13 21:16:40 +00:00
"priority": null,
"is_project_label": true
2016-11-04 11:52:38 +00:00
}
2014-08-12 12:16:25 +00:00
]
```
2019-09-27 15:06:16 +00:00
## Get a single project label
Get a single label for a given project.
2020-02-27 09:09:01 +00:00
```plaintext
2019-09-27 15:06:16 +00:00
GET /projects/:id/labels/:label_id
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2020-05-06 15:09:42 +00:00
| `label_id` | integer or string | yes | The ID or title of a project's label. |
2019-09-27 15:06:16 +00:00
| `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true` . |
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/labels/bug"
2019-09-27 15:06:16 +00:00
```
Example response:
```json
{
"id" : 1,
"name" : "bug",
"color" : "#d9534f",
"text_color" : "#FFFFFF",
"description": "Bug reported by user",
2019-12-30 12:09:15 +00:00
"description_html": "Bug reported by user",
2019-09-27 15:06:16 +00:00
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 1,
"subscribed": false,
"priority": 10,
"is_project_label": true
}
```
2014-08-12 12:16:25 +00:00
## Create a new label
2016-01-18 08:41:42 +00:00
Creates a new label for the given repository with the given name and color.
2020-02-27 09:09:01 +00:00
```plaintext
2014-08-12 12:16:25 +00:00
POST /projects/:id/labels
```
2016-03-24 18:38:37 +00:00
| Attribute | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
2017-04-08 08:54:00 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-03-24 18:38:37 +00:00
| `name` | string | yes | The name of the label |
2017-03-29 11:45:15 +00:00
| `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB ) or one of the [CSS color names ](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords ) |
2016-03-24 18:38:37 +00:00
| `description` | string | no | The description of the label |
2016-11-04 10:13:17 +00:00
| `priority` | integer | no | The priority of the label. Must be greater or equal than zero or `null` to remove the priority. |
2016-01-18 08:41:42 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --data "name=feature& color=#5843AD" --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/labels"
2016-01-18 08:41:42 +00:00
```
2014-08-12 12:16:25 +00:00
2016-01-18 08:41:42 +00:00
Example response:
2014-08-12 12:16:25 +00:00
2016-01-18 08:41:42 +00:00
```json
{
2016-11-04 11:52:38 +00:00
"id" : 10,
"name" : "feature",
"color" : "#5843AD",
2019-02-12 18:36:45 +00:00
"text_color" : "#FFFFFF",
2016-11-04 11:52:38 +00:00
"description":null,
2019-12-30 12:09:15 +00:00
"description_html":null,
2016-11-04 11:52:38 +00:00
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false,
2019-02-13 21:16:40 +00:00
"priority": null,
"is_project_label": true
2016-01-18 08:41:42 +00:00
}
```
2014-08-12 12:16:25 +00:00
## Delete a label
2016-01-18 08:41:42 +00:00
Deletes a label with a given name.
2020-02-27 09:09:01 +00:00
```plaintext
2019-09-27 15:06:16 +00:00
DELETE /projects/:id/labels/:label_id
2014-08-12 12:16:25 +00:00
```
2016-03-24 18:38:37 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2019-08-23 17:45:42 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2019-09-27 15:06:16 +00:00
| `label_id` | integer or string | yes | The ID or title of a group's label. |
2014-08-12 12:16:25 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-09-27 15:06:16 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/labels/bug"
2016-01-18 08:41:42 +00:00
```
2020-07-16 06:09:33 +00:00
NOTE: **Note:**
An older endpoint `DELETE /projects/:id/labels` with `name` in the parameters is still available, but deprecated.
2019-09-27 15:06:16 +00:00
2014-08-13 10:23:51 +00:00
## Edit an existing label
2016-01-18 08:41:42 +00:00
Updates an existing label with new name or new color. At least one parameter
2014-08-13 10:23:51 +00:00
is required, to update the label.
2020-02-27 09:09:01 +00:00
```plaintext
2019-09-27 15:06:16 +00:00
PUT /projects/:id/labels/:label_id
2014-08-13 10:23:51 +00:00
```
2016-03-24 18:38:37 +00:00
| Attribute | Type | Required | Description |
| --------------- | ------- | --------------------------------- | ------------------------------- |
2017-04-08 08:54:00 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2019-09-27 15:06:16 +00:00
| `label_id` | integer or string | yes | The ID or title of a group's label. |
2016-10-09 13:42:11 +00:00
| `new_name` | string | yes if `color` is not provided | The new name of the label |
2017-03-29 11:45:15 +00:00
| `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB ) or one of the [CSS color names ](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords ) |
2016-03-24 18:38:37 +00:00
| `description` | string | no | The new description of the label |
2016-11-04 10:13:17 +00:00
| `priority` | integer | no | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. |
2020-01-30 15:09:15 +00:00
```shell
2019-09-27 15:06:16 +00:00
curl --request PUT --data "new_name=docs& color=#8E44AD& description=Documentation" --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/labels/documentation"
2016-01-18 08:41:42 +00:00
```
2014-08-13 10:23:51 +00:00
2016-01-18 08:41:42 +00:00
Example response:
2014-08-13 10:23:51 +00:00
2016-01-18 08:41:42 +00:00
```json
{
2016-11-04 11:52:38 +00:00
"id" : 8,
"name" : "docs",
"color" : "#8E44AD",
2019-02-12 18:36:45 +00:00
"text_color" : "#FFFFFF",
2016-11-04 11:52:38 +00:00
"description": "Documentation",
2019-12-30 12:09:15 +00:00
"description_html": "Documentation",
2016-11-04 11:52:38 +00:00
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 2,
"subscribed": false,
2019-02-13 21:16:40 +00:00
"priority": null,
"is_project_label": true
2016-01-18 08:41:42 +00:00
}
```
2016-05-12 20:48:09 +00:00
2020-07-16 06:09:33 +00:00
NOTE: **Note:**
An older endpoint `PUT /projects/:id/labels` with `name` or `label_id` in the parameters is still available, but deprecated.
2019-09-27 15:06:16 +00:00
2019-02-13 21:51:53 +00:00
## Promote a project label to a group label
2020-02-06 15:09:11 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25218) in GitLab 12.3.
2019-02-13 21:51:53 +00:00
Promotes a project label to a group label.
2020-02-27 09:09:01 +00:00
```plaintext
2019-09-27 15:06:16 +00:00
PUT /projects/:id/labels/:label_id/promote
2019-02-13 21:51:53 +00:00
```
| Attribute | Type | Required | Description |
| --------------- | ------- | --------------------------------- | ------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2019-09-27 15:06:16 +00:00
| `label_id` | integer or string | yes | The ID or title of a group's label. |
2019-02-13 21:51:53 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-09-27 15:06:16 +00:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/labels/documentation/promote"
2019-02-13 21:51:53 +00:00
```
Example response:
```json
{
"id" : 8,
"name" : "documentation",
"color" : "#8E44AD",
"description": "Documentation",
2019-12-30 12:09:15 +00:00
"description_html": "Documentation",
2019-02-13 21:51:53 +00:00
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 2,
"subscribed": false
}
```
2020-07-16 06:09:33 +00:00
NOTE: **Note:**
An older endpoint `PUT /projects/:id/labels/promote` with `name` in the parameters is still available, but deprecated.
2019-09-27 15:06:16 +00:00
2016-05-12 20:48:09 +00:00
## Subscribe to a label
2017-02-17 09:49:45 +00:00
Subscribes the authenticated user to a label to receive notifications.
2016-11-24 17:28:52 +00:00
If the user is already subscribed to the label, the status code `304`
is returned.
2016-05-12 20:48:09 +00:00
2020-02-27 09:09:01 +00:00
```plaintext
2017-02-17 09:49:45 +00:00
POST /projects/:id/labels/:label_id/subscribe
2016-05-12 20:48:09 +00:00
```
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
2017-04-08 08:54:00 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-05-12 20:48:09 +00:00
| `label_id` | integer or string | yes | The ID or title of a project's label |
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/labels/1/subscribe"
2016-05-12 20:48:09 +00:00
```
Example response:
```json
{
2016-11-04 11:52:38 +00:00
"id" : 1,
"name" : "bug",
"color" : "#d9534f",
2019-02-12 18:36:45 +00:00
"text_color" : "#FFFFFF",
2016-11-04 11:52:38 +00:00
"description": "Bug reported by user",
2019-12-30 12:09:15 +00:00
"description_html": "Bug reported by user",
2016-11-04 11:52:38 +00:00
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 1,
"subscribed": true,
2019-02-13 21:16:40 +00:00
"priority": null,
"is_project_label": true
2016-05-12 20:48:09 +00:00
}
```
## Unsubscribe from a label
Unsubscribes the authenticated user from a label to not receive notifications
2016-11-24 17:28:52 +00:00
from it. If the user is not subscribed to the label, the
status code `304` is returned.
2016-05-12 20:48:09 +00:00
2020-02-27 09:09:01 +00:00
```plaintext
2017-02-23 12:37:19 +00:00
POST /projects/:id/labels/:label_id/unsubscribe
2016-05-12 20:48:09 +00:00
```
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
2017-04-08 08:54:00 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-05-12 20:48:09 +00:00
| `label_id` | integer or string | yes | The ID or title of a project's label |
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/labels/1/unsubscribe"
2016-05-12 20:48:09 +00:00
```