labels.md 7.15 KB
Newer Older
1
# Labels API
2 3 4

## List labels

5
Get all labels for a given project.
6 7 8 9 10

```
GET /projects/:id/labels
```

11 12
| Attribute | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
13
| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
14 15

```bash
16
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/labels
17 18 19 20
```

Example response:

21 22
```json
[
Rares Sfirlogea's avatar
Rares Sfirlogea committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
  {
    "id" : 1,
    "name" : "bug",
    "color" : "#d9534f",
    "description": "Bug reported by user",
    "open_issues_count": 1,
    "closed_issues_count": 0,
    "open_merge_requests_count": 1,
    "subscribed": false,
    "priority": 10
  },
  {
    "id" : 4,
    "color" : "#d9534f",
    "name" : "confirmed",
    "description": "Confirmed issue",
    "open_issues_count": 2,
    "closed_issues_count": 5,
    "open_merge_requests_count": 0,
    "subscribed": false,
    "priority": null
  },
  {
    "id" : 7,
    "name" : "critical",
    "color" : "#d9534f",
    "description": "Critical issue. Need fix ASAP",
    "open_issues_count": 1,
    "closed_issues_count": 3,
    "open_merge_requests_count": 1,
    "subscribed": false,
    "priority": null
  },
  {
    "id" : 8,
    "name" : "documentation",
    "color" : "#f0ad4e",
    "description": "Issue about documentation",
    "open_issues_count": 1,
    "closed_issues_count": 0,
    "open_merge_requests_count": 2,
    "subscribed": false,
    "priority": null
  },
  {
    "id" : 9,
    "color" : "#5cb85c",
    "name" : "enhancement",
    "description": "Enhancement proposal",
    "open_issues_count": 1,
    "closed_issues_count": 0,
    "open_merge_requests_count": 1,
    "subscribed": true,
    "priority": null
  }
78 79 80 81 82
]
```

## Create a new label

83 84
Creates a new label for the given repository with the given name and color.

85 86 87 88
```
POST /projects/:id/labels
```

89 90
| Attribute     | Type    | Required | Description                  |
| ------------- | ------- | -------- | ---------------------------- |
91
| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
92
| `name`        | string  | yes      | The name of the label        |
93
| `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) |
94
| `description` | string  | no       | The description of the label |
95
| `priority`    | integer | no       | The priority of the label. Must be greater or equal than zero or `null` to remove the priority. |
96 97

```bash
98
curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels"
99
```
100

101
Example response:
102

103 104
```json
{
Rares Sfirlogea's avatar
Rares Sfirlogea committed
105 106 107 108 109 110 111 112 113
  "id" : 10,
  "name" : "feature",
  "color" : "#5843AD",
  "description":null,
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false,
  "priority": null
114 115
}
```
116 117 118

## Delete a label

119 120
Deletes a label with a given name.

121 122 123 124
```
DELETE /projects/:id/labels
```

125 126
| Attribute | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
127
| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
128
| `name`    | string  | yes      | The name of the label |
129

130
```bash
131
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels?name=bug"
132 133
```

Robert Schilling's avatar
Robert Schilling committed
134 135
## Edit an existing label

136
Updates an existing label with new name or new color. At least one parameter
Robert Schilling's avatar
Robert Schilling committed
137 138 139 140 141 142
is required, to update the label.

```
PUT /projects/:id/labels
```

143 144
| Attribute       | Type    | Required                          | Description                      |
| --------------- | ------- | --------------------------------- | -------------------------------  |
145
| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
146
| `name`          | string  | yes                               | The name of the existing label   |
147
| `new_name`      | string  | yes if `color` is not provided    | The new name of the label        |
148
| `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) |
149
| `description`   | string  | no                                | The new description of the label |
150 151
| `priority`    | integer | no       | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. |

152 153

```bash
154
curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels"
155
```
Robert Schilling's avatar
Robert Schilling committed
156

157
Example response:
Robert Schilling's avatar
Robert Schilling committed
158

159 160
```json
{
Rares Sfirlogea's avatar
Rares Sfirlogea committed
161 162 163 164 165 166 167 168 169
  "id" : 8,
  "name" : "docs",
  "color" : "#8E44AD",
  "description": "Documentation",
  "open_issues_count": 1,
  "closed_issues_count": 0,
  "open_merge_requests_count": 2,
  "subscribed": false,
  "priority": null
170 171
}
```
172 173 174

## Subscribe to a label

Robert Schilling's avatar
Robert Schilling committed
175
Subscribes the authenticated user to a label to receive notifications.
176 177
If the user is already subscribed to the label, the status code `304`
is returned.
178 179

```
Robert Schilling's avatar
Robert Schilling committed
180
POST /projects/:id/labels/:label_id/subscribe
181 182 183 184
```

| Attribute  | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
185
| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
186 187 188
| `label_id` | integer or string | yes      | The ID or title of a project's label |

```bash
189
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/labels/1/subscribe
190 191 192 193 194 195
```

Example response:

```json
{
Rares Sfirlogea's avatar
Rares Sfirlogea committed
196 197 198 199 200 201 202 203 204
  "id" : 1,
  "name" : "bug",
  "color" : "#d9534f",
  "description": "Bug reported by user",
  "open_issues_count": 1,
  "closed_issues_count": 0,
  "open_merge_requests_count": 1,
  "subscribed": true,
  "priority": null
205 206 207 208 209 210
}
```

## Unsubscribe from a label

Unsubscribes the authenticated user from a label to not receive notifications
211 212
from it. If the user is not subscribed to the label, the
status code `304` is returned.
213 214

```
215
POST /projects/:id/labels/:label_id/unsubscribe
216 217 218 219
```

| Attribute  | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
220
| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
221 222 223
| `label_id` | integer or string | yes      | The ID or title of a project's label |

```bash
224
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/labels/1/unsubscribe
225
```