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

## List labels

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

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

11 12 13
| Attribute | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
| `id`      | integer | yes      | The ID of the project |
14 15

```bash
16
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/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 91 92 93 94
| Attribute     | Type    | Required | Description                  |
| ------------- | ------- | -------- | ---------------------------- |
| `id`          | integer | yes      | The ID of the project        |
| `name`        | string  | yes      | The name of the label        |
| `color`       | string  | yes      | The color of the label in 6-digit hex notation with leading `#` sign |
| `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: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/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 127 128
| Attribute | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
| `id`      | integer | yes      | The ID of the project |
| `name`    | string  | yes      | The name of the label |
129

130
```bash
131
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug"
132 133 134 135 136 137
```

Example response:

```json
{
Rares Sfirlogea's avatar
Rares Sfirlogea committed
138 139 140 141 142 143 144 145 146
  "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": null
147 148
}
```
Robert Schilling's avatar
Robert Schilling committed
149 150 151

## Edit an existing label

152
Updates an existing label with new name or new color. At least one parameter
Robert Schilling's avatar
Robert Schilling committed
153 154 155 156 157 158
is required, to update the label.

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

159 160 161 162
| Attribute       | Type    | Required                          | Description                      |
| --------------- | ------- | --------------------------------- | -------------------------------  |
| `id`            | integer | yes                               | The ID of the project            |
| `name`          | string  | yes                               | The name of the existing label   |
163
| `new_name`      | string  | yes if `color` is not provided    | The new name of the label        |
164 165
| `color`         | string  | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign |
| `description`   | string  | no                                | The new description of the label |
166 167
| `priority`    | integer | no       | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. |

168 169

```bash
170
curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
171
```
Robert Schilling's avatar
Robert Schilling committed
172

173
Example response:
Robert Schilling's avatar
Robert Schilling committed
174

175 176
```json
{
Rares Sfirlogea's avatar
Rares Sfirlogea committed
177 178 179 180 181 182 183 184 185
  "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
186 187
}
```
188 189 190

## Subscribe to a label

191 192 193
Subscribes the authenticated user to a label to receive notifications. 
If the user is already subscribed to the label, the status code `304`
is returned.
194 195 196 197 198 199 200 201 202 203 204

```
POST /projects/:id/labels/:label_id/subscription
```

| Attribute  | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id`       | integer           | yes      | The ID of a project                  |
| `label_id` | integer or string | yes      | The ID or title of a project's label |

```bash
205
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/labels/1/subscription
206 207 208 209 210 211
```

Example response:

```json
{
Rares Sfirlogea's avatar
Rares Sfirlogea committed
212 213 214 215 216 217 218 219 220
  "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
221 222 223 224 225 226
}
```

## Unsubscribe from a label

Unsubscribes the authenticated user from a label to not receive notifications
227 228
from it. If the user is not subscribed to the label, the
status code `304` is returned.
229 230 231 232 233 234 235 236 237 238 239

```
DELETE /projects/:id/labels/:label_id/subscription
```

| Attribute  | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id`       | integer           | yes      | The ID of a project                  |
| `label_id` | integer or string | yes      | The ID or title of a project's label |

```bash
240
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/labels/1/subscription
241 242 243 244 245 246
```

Example response:

```json
{
Rares Sfirlogea's avatar
Rares Sfirlogea committed
247 248 249 250 251 252 253 254 255
  "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": null
256 257
}
```