BigW Consortium Gitlab

issues.md 35.5 KB
Newer Older
1
# Issues API
2

3 4 5 6 7 8 9 10 11 12 13 14
Every API call to issues must be authenticated.

If a user is not a member of a project and the project is private, a `GET`
request on that project will result to a `404` status code.

## Issues pagination

By default, `GET` requests return 20 results at a time because the API results
are paginated.

Read more on [pagination](README.md#pagination).

Nihad Abbasov committed
15 16
## List issues

17
Get all issues created by the authenticated user.
Nihad Abbasov committed
18 19 20

```
GET /issues
21 22
GET /issues?state=opened
GET /issues?state=closed
23 24 25
GET /issues?labels=foo
GET /issues?labels=foo,bar
GET /issues?labels=foo,bar&state=opened
26 27
GET /issues?milestone=1.0.0
GET /issues?milestone=1.0.0&state=opened
28
GET /issues?iids[]=42&iids[]=43
29
GET /issues?search=issue+title+or+description
Nihad Abbasov committed
30 31
```

32
| Attribute   | Type           | Required | Description                                                                                                                 |
33
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------|
34 35 36 37 38 39
| `state`     | string         | no       | Return all issues or just those that are `opened` or `closed`                                                               |
| `labels`    | string         | no       | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
| `milestone` | string         | no       | The milestone title                                                                                                         |
| `iids`      | Array[integer] | no       | Return only the issues having the given `iid`                                                                               |
| `order_by`  | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                     |
| `sort`      | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                          |
40
| `search`    | string         | no       | Search issues against their `title` and `description`                                                                       |
41 42

```bash
43
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues
44
```
45

46
Example response:
47

Nihad Abbasov committed
48 49
```json
[
50 51 52 53 54 55
   {
      "state" : "opened",
      "description" : "Ratione dolores corrupti mollitia soluta quia.",
      "author" : {
         "state" : "active",
         "id" : 18,
56
         "web_url" : "https://gitlab.example.com/eileen.lowe",
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
         "name" : "Alexandra Bashirian",
         "avatar_url" : null,
         "username" : "eileen.lowe"
      },
      "milestone" : {
         "project_id" : 1,
         "description" : "Ducimus nam enim ex consequatur cumque ratione.",
         "state" : "closed",
         "due_date" : null,
         "iid" : 2,
         "created_at" : "2016-01-04T15:31:39.996Z",
         "title" : "v4.0",
         "id" : 17,
         "updated_at" : "2016-01-04T15:31:39.996Z"
      },
      "project_id" : 1,
73 74 75 76 77 78 79 80
      "assignees" : [{
         "state" : "active",
         "id" : 1,
         "name" : "Administrator",
         "web_url" : "https://gitlab.example.com/root",
         "avatar_url" : null,
         "username" : "root"
      }],
81 82 83 84
      "assignee" : {
         "state" : "active",
         "id" : 1,
         "name" : "Administrator",
85
         "web_url" : "https://gitlab.example.com/root",
86 87 88 89 90 91 92 93
         "avatar_url" : null,
         "username" : "root"
      },
      "updated_at" : "2016-01-04T15:31:51.081Z",
      "id" : 76,
      "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
      "created_at" : "2016-01-04T15:31:51.081Z",
      "iid" : 6,
94
      "labels" : [],
95
      "user_notes_count": 1,
96
      "due_date": "2016-07-22",
97 98
      "web_url": "http://example.com/example/example/issues/6",
      "confidential": false
99
   }
Nihad Abbasov committed
100 101 102
]
```

103
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
104

105 106 107 108 109 110 111 112 113 114 115 116 117
## List group issues

Get a list of a group's issues.

```
GET /groups/:id/issues
GET /groups/:id/issues?state=opened
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?labels=foo
GET /groups/:id/issues?labels=foo,bar
GET /groups/:id/issues?labels=foo,bar&state=opened
GET /groups/:id/issues?milestone=1.0.0
GET /groups/:id/issues?milestone=1.0.0&state=opened
118
GET /groups/:id/issues?iids[]=42&iids[]=43
119
GET /groups/:id/issues?search=issue+title+or+description
120 121
```

122
| Attribute   | Type           | Required | Description                                                                                                                 |
123
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------|
124
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user  |
125 126 127 128 129 130 131
| `state`     | string         | no       | Return all issues or just those that are `opened` or `closed`                                                               |
| `labels`    | string         | no       | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
| `iids`      | Array[integer] | no       | Return only the issues having the given `iid`                                                                               |
| `milestone` | string         | no       | The milestone title                                                                                                         |
| `order_by`  | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                     |
| `sort`      | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                          |
| `search`    | string         | no       | Search group issues against their `title` and `description`                                                                  |
132 133 134


```bash
135
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/4/issues
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
```

Example response:

```json
[
   {
      "project_id" : 4,
      "milestone" : {
         "due_date" : null,
         "project_id" : 4,
         "state" : "closed",
         "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
         "iid" : 3,
         "id" : 11,
         "title" : "v3.0",
         "created_at" : "2016-01-04T15:31:39.788Z",
         "updated_at" : "2016-01-04T15:31:39.788Z"
      },
      "author" : {
         "state" : "active",
157
         "web_url" : "https://gitlab.example.com/root",
158 159 160 161 162 163 164 165
         "avatar_url" : null,
         "username" : "root",
         "id" : 1,
         "name" : "Administrator"
      },
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "state" : "closed",
      "iid" : 1,
166 167 168 169 170 171 172 173
      "assignees" : [{
         "avatar_url" : null,
         "web_url" : "https://gitlab.example.com/lennie",
         "state" : "active",
         "username" : "lennie",
         "id" : 9,
         "name" : "Dr. Luella Kovacek"
      }],
174 175
      "assignee" : {
         "avatar_url" : null,
176
         "web_url" : "https://gitlab.example.com/lennie",
177 178 179 180 181 182 183 184 185 186
         "state" : "active",
         "username" : "lennie",
         "id" : 9,
         "name" : "Dr. Luella Kovacek"
      },
      "labels" : [],
      "id" : 41,
      "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
      "updated_at" : "2016-01-04T15:31:46.176Z",
      "created_at" : "2016-01-04T15:31:46.176Z",
187
      "user_notes_count": 1,
188
      "due_date": null,
189 190
      "web_url": "http://example.com/example/example/issues/1",
      "confidential": false
191 192 193 194
   }
]
```

195
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
196

Nihad Abbasov committed
197 198
## List project issues

199
Get a list of a project's issues.
Nihad Abbasov committed
200 201 202

```
GET /projects/:id/issues
203 204
GET /projects/:id/issues?state=opened
GET /projects/:id/issues?state=closed
205 206 207
GET /projects/:id/issues?labels=foo
GET /projects/:id/issues?labels=foo,bar
GET /projects/:id/issues?labels=foo,bar&state=opened
208 209
GET /projects/:id/issues?milestone=1.0.0
GET /projects/:id/issues?milestone=1.0.0&state=opened
210
GET /projects/:id/issues?iids[]=42&iids[]=43
211
GET /projects/:id/issues?search=issue+title+or+description
Nihad Abbasov committed
212 213
```

214
| Attribute   | Type           | Required | Description                                                                                                                 |
215
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------|
216
| `id`        | integer/string        | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
217 218 219 220 221 222 223
| `iids`      | Array[integer] | no       | Return only the milestone having the given `iid`                                                                            |
| `state`     | string         | no       | Return all issues or just those that are `opened` or `closed`                                                               |
| `labels`    | string         | no       | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
| `milestone` | string         | no       | The milestone title                                                                                                         |
| `order_by`  | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                     |
| `sort`      | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                          |
| `search`    | string         | no       | Search project issues against their `title` and `description`                                                                |
224 225 226


```bash
227
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues
228 229 230
```

Example response:
Nihad Abbasov committed
231

232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
```json
[
   {
      "project_id" : 4,
      "milestone" : {
         "due_date" : null,
         "project_id" : 4,
         "state" : "closed",
         "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
         "iid" : 3,
         "id" : 11,
         "title" : "v3.0",
         "created_at" : "2016-01-04T15:31:39.788Z",
         "updated_at" : "2016-01-04T15:31:39.788Z"
      },
      "author" : {
         "state" : "active",
249
         "web_url" : "https://gitlab.example.com/root",
250 251 252 253 254 255 256 257
         "avatar_url" : null,
         "username" : "root",
         "id" : 1,
         "name" : "Administrator"
      },
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "state" : "closed",
      "iid" : 1,
258 259 260 261 262 263 264 265
      "assignees" : [{
         "avatar_url" : null,
         "web_url" : "https://gitlab.example.com/lennie",
         "state" : "active",
         "username" : "lennie",
         "id" : 9,
         "name" : "Dr. Luella Kovacek"
      }],
266 267
      "assignee" : {
         "avatar_url" : null,
268
         "web_url" : "https://gitlab.example.com/lennie",
269 270 271 272 273 274 275 276 277
         "state" : "active",
         "username" : "lennie",
         "id" : 9,
         "name" : "Dr. Luella Kovacek"
      },
      "labels" : [],
      "id" : 41,
      "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
      "updated_at" : "2016-01-04T15:31:46.176Z",
278
      "created_at" : "2016-01-04T15:31:46.176Z",
279
      "user_notes_count": 1,
280
      "due_date": "2016-07-22",
281 282
      "web_url": "http://example.com/example/example/issues/1",
      "confidential": false
283 284 285
   }
]
```
286

287
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
288

Nihad Abbasov committed
289 290
## Single issue

291
Get a single project issue.
Nihad Abbasov committed
292 293

```
294
GET /projects/:id/issues/:issue_iid
Nihad Abbasov committed
295 296
```

297
| Attribute   | Type    | Required | Description                          |
298
|-------------|---------|----------|--------------------------------------|
299
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
300
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
Nihad Abbasov committed
301

302
```bash
303
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/41
304 305 306
```

Example response:
Nihad Abbasov committed
307 308 309

```json
{
310 311 312 313 314 315 316 317 318 319 320 321 322 323
   "project_id" : 4,
   "milestone" : {
      "due_date" : null,
      "project_id" : 4,
      "state" : "closed",
      "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
      "iid" : 3,
      "id" : 11,
      "title" : "v3.0",
      "created_at" : "2016-01-04T15:31:39.788Z",
      "updated_at" : "2016-01-04T15:31:39.788Z"
   },
   "author" : {
      "state" : "active",
324
      "web_url" : "https://gitlab.example.com/root",
325 326 327 328 329 330 331 332
      "avatar_url" : null,
      "username" : "root",
      "id" : 1,
      "name" : "Administrator"
   },
   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
   "state" : "closed",
   "iid" : 1,
333 334 335 336 337 338 339 340
   "assignees" : [{
      "avatar_url" : null,
      "web_url" : "https://gitlab.example.com/lennie",
      "state" : "active",
      "username" : "lennie",
      "id" : 9,
      "name" : "Dr. Luella Kovacek"
   }],
341 342
   "assignee" : {
      "avatar_url" : null,
343
      "web_url" : "https://gitlab.example.com/lennie",
344 345 346 347 348 349 350 351 352
      "state" : "active",
      "username" : "lennie",
      "id" : 9,
      "name" : "Dr. Luella Kovacek"
   },
   "labels" : [],
   "id" : 41,
   "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
   "updated_at" : "2016-01-04T15:31:46.176Z",
353
   "created_at" : "2016-01-04T15:31:46.176Z",
354
   "subscribed": false,
355
   "user_notes_count": 1,
356
   "due_date": null,
357 358
   "web_url": "http://example.com/example/example/issues/1",
   "confidential": false
Nihad Abbasov committed
359 360 361
}
```

362
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
363

Nihad Abbasov committed
364 365
## New issue

366
Creates a new project issue.
Nihad Abbasov committed
367 368 369 370 371

```
POST /projects/:id/issues
```

372 373
| Attribute                                 | Type           | Required | Description  |
|-------------------------------------------|----------------|----------|--------------|
374
| `id`                                      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
375 376 377
| `title`                                   | string  | yes      | The title of an issue |
| `description`                             | string  | no       | The description of an issue  |
| `confidential`                            | boolean | no       | Set an issue to be confidential. Default is `false`.  |
378
| `assignee_ids`                            | Array[integer] | no       | The ID of the users to assign issue |
379 380 381 382 383 384
| `milestone_id`                            | integer | no       | The ID of a milestone to assign issue  |
| `labels`                                  | string  | no       | Comma-separated label names for an issue  |
| `created_at`                              | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
| `due_date`                                | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` |
| `merge_request_to_resolve_discussions_of` | integer | no       | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.|
| `discussion_to_resolve`                   | string  | no       | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. |
385 386

```bash
387
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug
388
```
Nihad Abbasov committed
389

390
Example response:
Nihad Abbasov committed
391

392 393 394 395 396 397 398 399
```json
{
   "project_id" : 4,
   "id" : 84,
   "created_at" : "2016-01-07T12:44:33.959Z",
   "iid" : 14,
   "title" : "Issues with auth",
   "state" : "opened",
400
   "assignees" : [],
401 402 403 404 405 406 407 408
   "assignee" : null,
   "labels" : [
      "bug"
   ],
   "author" : {
      "name" : "Alexandra Bashirian",
      "avatar_url" : null,
      "state" : "active",
409
      "web_url" : "https://gitlab.example.com/eileen.lowe",
410 411 412 413 414
      "id" : 18,
      "username" : "eileen.lowe"
   },
   "description" : null,
   "updated_at" : "2016-01-07T12:44:33.959Z",
415
   "milestone" : null,
416
   "subscribed" : true,
417
   "user_notes_count": 0,
418
   "due_date": null,
419 420
   "web_url": "http://example.com/example/example/issues/14",
   "confidential": false
421 422
}
```
423

424
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
425

Nihad Abbasov committed
426 427
## Edit issue

428 429 430
Updates an existing project issue. This call is also used to mark an issue as
closed.

Nihad Abbasov committed
431
```
432
PUT /projects/:id/issues/:issue_iid
Nihad Abbasov committed
433 434
```

435
| Attribute      | Type    | Required | Description                                                                                                |
436
|----------------|---------|----------|------------------------------------------------------------------------------------------------------------|
437
| `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
438 439 440 441
| `issue_iid`    | integer | yes      | The internal ID of a project's issue                                                                       |
| `title`        | string  | no       | The title of an issue                                                                                      |
| `description`  | string  | no       | The description of an issue                                                                                |
| `confidential` | boolean | no       | Updates an issue to be confidential                                                                        |
442
| `assignee_ids`  | Array[integer] | no       | The ID of the users to assign the issue to                                                                    |
443 444 445 446 447
| `milestone_id` | integer | no       | The ID of a milestone to assign the issue to                                                               |
| `labels`       | string  | no       | Comma-separated label names for an issue                                                                   |
| `state_event`  | string  | no       | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it                      |
| `updated_at`   | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
| `due_date`     | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`                                           |
448 449

```bash
450
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close
451
```
Nihad Abbasov committed
452

453
Example response:
454

455 456 457 458 459 460 461 462 463
```json
{
   "created_at" : "2016-01-07T12:46:01.410Z",
   "author" : {
      "name" : "Alexandra Bashirian",
      "avatar_url" : null,
      "username" : "eileen.lowe",
      "id" : 18,
      "state" : "active",
464
      "web_url" : "https://gitlab.example.com/eileen.lowe"
465 466 467 468 469 470 471 472 473 474 475
   },
   "state" : "closed",
   "title" : "Issues with auth",
   "project_id" : 4,
   "description" : null,
   "updated_at" : "2016-01-07T12:55:16.213Z",
   "iid" : 15,
   "labels" : [
      "bug"
   ],
   "id" : 85,
476
   "assignees" : [],
477
   "assignee" : null,
478
   "milestone" : null,
479
   "subscribed" : true,
480
   "user_notes_count": 0,
481
   "due_date": "2016-07-22",
482 483
   "web_url": "http://example.com/example/example/issues/15",
   "confidential": false
484 485
}
```
486

487
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
488

489
## Delete an issue
490

491
Only for admins and project owners. Soft deletes the issue in question.
492 493

```
494
DELETE /projects/:id/issues/:issue_iid
495 496
```

497
| Attribute   | Type    | Required | Description                          |
498
|-------------|---------|----------|--------------------------------------|
499
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
500
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
501 502

```bash
503
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85
504 505
```

506 507
## Move an issue

508
Moves an issue to a different project. If the target project
509 510
equals the source project or the user has insufficient permissions to move an
issue, error `400` together with an explaining error message is returned.
511

512 513 514
If a given label and/or milestone with the same name also exists in the target
project, it will then be assigned to the issue that is being moved.

515
```
516
POST /projects/:id/issues/:issue_iid/move
517 518
```

519
| Attribute       | Type    | Required | Description                          |
520
|-----------------|---------|----------|--------------------------------------|
521
| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
522 523
| `issue_iid`     | integer | yes      | The internal ID of a project's issue |
| `to_project_id` | integer | yes      | The ID of the new project            |
524 525

```bash
526
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85/move
527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542
```

Example response:

```json
{
  "id": 92,
  "iid": 11,
  "project_id": 5,
  "title": "Sit voluptas tempora quisquam aut doloribus et.",
  "description": "Repellat voluptas quibusdam voluptatem exercitationem.",
  "state": "opened",
  "created_at": "2016-04-05T21:41:45.652Z",
  "updated_at": "2016-04-07T12:20:17.596Z",
  "labels": [],
  "milestone": null,
543 544 545 546 547 548 549 550
  "assignees": [{
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/axel.block"
  }],
551 552 553 554 555 556
  "assignee": {
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
557
    "web_url": "https://gitlab.example.com/axel.block"
558 559 560 561 562 563 564
  },
  "author": {
    "name": "Kris Steuber",
    "username": "solon.cremin",
    "id": 10,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80&d=identicon",
565
    "web_url": "https://gitlab.example.com/solon.cremin"
566
  },
567
  "due_date": null,
568 569
  "web_url": "http://example.com/example/example/issues/11",
  "confidential": false
570 571 572
}
```

573
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
574

575 576
## Subscribe to an issue

577
Subscribes the authenticated user to an issue to receive notifications.
578 579
If the user is already subscribed to the issue, the status code `304`
is returned.
580 581

```
582
POST /projects/:id/issues/:issue_iid/subscribe
583 584
```

585
| Attribute   | Type    | Required | Description                          |
586
|-------------|---------|----------|--------------------------------------|
587
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
588
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
589 590

```bash
591
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe
592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607
```

Example response:

```json
{
  "id": 92,
  "iid": 11,
  "project_id": 5,
  "title": "Sit voluptas tempora quisquam aut doloribus et.",
  "description": "Repellat voluptas quibusdam voluptatem exercitationem.",
  "state": "opened",
  "created_at": "2016-04-05T21:41:45.652Z",
  "updated_at": "2016-04-07T12:20:17.596Z",
  "labels": [],
  "milestone": null,
608 609 610 611 612 613 614 615
  "assignees": [{
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/axel.block"
  }],
616 617 618 619 620 621
  "assignee": {
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
622
    "web_url": "https://gitlab.example.com/axel.block"
623 624 625 626 627 628 629
  },
  "author": {
    "name": "Kris Steuber",
    "username": "solon.cremin",
    "id": 10,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80&d=identicon",
630
    "web_url": "https://gitlab.example.com/solon.cremin"
631
  },
632
  "due_date": null,
633 634
  "web_url": "http://example.com/example/example/issues/11",
  "confidential": false
635 636 637
}
```

638
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
639

640 641
## Unsubscribe from an issue

642
Unsubscribes the authenticated user from the issue to not receive notifications
643 644
from it. If the user is not subscribed to the issue, the
status code `304` is returned.
645 646

```
647
POST /projects/:id/issues/:issue_iid/unsubscribe
648 649
```

650
| Attribute   | Type    | Required | Description                          |
651
|-------------|---------|----------|--------------------------------------|
652
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
653
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
654 655

```bash
656
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe
657 658
```

659 660
## Create a todo

661
Manually creates a todo for the current user on an issue. If
662 663 664 665
there already exists a todo for the user on that issue, status code `304` is
returned.

```
666
POST /projects/:id/issues/:issue_iid/todo
667 668
```

669
| Attribute   | Type    | Required | Description                          |
670
|-------------|---------|----------|--------------------------------------|
671
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
672
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
673 674

```bash
675
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/todo
676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695
```

Example response:

```json
{
  "id": 112,
  "project": {
    "id": 5,
    "name": "Gitlab Ci",
    "name_with_namespace": "Gitlab Org / Gitlab Ci",
    "path": "gitlab-ci",
    "path_with_namespace": "gitlab-org/gitlab-ci"
  },
  "author": {
    "name": "Administrator",
    "username": "root",
    "id": 1,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
696
    "web_url": "https://gitlab.example.com/root"
697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720
  },
  "action_name": "marked",
  "target_type": "Issue",
  "target": {
    "id": 93,
    "iid": 10,
    "project_id": 5,
    "title": "Vel voluptas atque dicta mollitia adipisci qui at.",
    "description": "Tempora laboriosam sint magni sed voluptas similique.",
    "state": "closed",
    "created_at": "2016-06-17T07:47:39.486Z",
    "updated_at": "2016-07-01T11:09:13.998Z",
    "labels": [],
    "milestone": {
      "id": 26,
      "iid": 1,
      "project_id": 5,
      "title": "v0.0",
      "description": "Accusantium nostrum rerum quae quia quis nesciunt suscipit id.",
      "state": "closed",
      "created_at": "2016-06-17T07:47:33.832Z",
      "updated_at": "2016-06-17T07:47:33.832Z",
      "due_date": null
    },
721 722 723 724 725 726 727 728
    "assignees": [{
      "name": "Jarret O'Keefe",
      "username": "francisca",
      "id": 14,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/francisca"
    }],
729 730 731 732 733 734
    "assignee": {
      "name": "Jarret O'Keefe",
      "username": "francisca",
      "id": 14,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon",
735
      "web_url": "https://gitlab.example.com/francisca"
736 737 738 739 740 741 742
    },
    "author": {
      "name": "Maxie Medhurst",
      "username": "craig_rutherford",
      "id": 12,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
743
      "web_url": "https://gitlab.example.com/craig_rutherford"
744 745 746 747
    },
    "subscribed": true,
    "user_notes_count": 7,
    "upvotes": 0,
748 749
    "downvotes": 0,
    "due_date": null,
750 751
    "web_url": "http://example.com/example/example/issues/110",
    "confidential": false
752 753 754 755 756 757 758 759
  },
  "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/issues/10",
  "body": "Vel voluptas atque dicta mollitia adipisci qui at.",
  "state": "pending",
  "created_at": "2016-07-01T11:09:13.992Z"
}
```

760
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
761

762 763 764 765 766
## Set a time estimate for an issue

Sets an estimated time of work for this issue.

```
767
POST /projects/:id/issues/:issue_iid/time_estimate
768 769
```

770
| Attribute   | Type    | Required | Description                              |
771
|-------------|---------|----------|------------------------------------------|
772
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
773 774
| `issue_iid` | integer | yes      | The internal ID of a project's issue     |
| `duration`  | string  | yes      | The duration in human format. e.g: 3h30m |
775 776

```bash
777
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m
778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795
```

Example response:

```json
{
  "human_time_estimate": "3h 30m",
  "human_total_time_spent": null,
  "time_estimate": 12600,
  "total_time_spent": 0
}
```

## Reset the time estimate for an issue

Resets the estimated time for this issue to 0 seconds.

```
796
POST /projects/:id/issues/:issue_iid/reset_time_estimate
797 798
```

799
| Attribute   | Type    | Required | Description                          |
800
|-------------|---------|----------|--------------------------------------|
801
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
802
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
803 804

```bash
805
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate
806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823
```

Example response:

```json
{
  "human_time_estimate": null,
  "human_total_time_spent": null,
  "time_estimate": 0,
  "total_time_spent": 0
}
```

## Add spent time for an issue

Adds spent time for this issue

```
824
POST /projects/:id/issues/:issue_iid/add_spent_time
825 826
```

827
| Attribute   | Type    | Required | Description                              |
828
|-------------|---------|----------|------------------------------------------|
829
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
830 831
| `issue_iid` | integer | yes      | The internal ID of a project's issue     |
| `duration`  | string  | yes      | The duration in human format. e.g: 3h30m |
832 833

```bash
834
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h
835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852
```

Example response:

```json
{
  "human_time_estimate": null,
  "human_total_time_spent": "1h",
  "time_estimate": 0,
  "total_time_spent": 3600
}
```

## Reset spent time for an issue

Resets the total spent time for this issue to 0 seconds.

```
853
POST /projects/:id/issues/:issue_iid/reset_spent_time
854 855
```

856
| Attribute   | Type    | Required | Description                          |
857
|-------------|---------|----------|--------------------------------------|
858
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
859
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
860 861

```bash
862
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time
863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878
```

Example response:

```json
{
  "human_time_estimate": null,
  "human_total_time_spent": null,
  "time_estimate": 0,
  "total_time_spent": 0
}
```

## Get time tracking stats

```
879
GET /projects/:id/issues/:issue_iid/time_stats
880 881
```

882
| Attribute   | Type    | Required | Description                          |
883
|-------------|---------|----------|--------------------------------------|
884
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user  |
885
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
886 887

```bash
888
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats
889 890 891 892 893 894 895 896 897 898 899 900 901
```

Example response:

```json
{
  "human_time_estimate": "2h",
  "human_total_time_spent": "1h",
  "time_estimate": 7200,
  "total_time_spent": 3600
}
```

902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962
## List merge requests that will close issue on merge

Get all the merge requests that will close issue when merged.

```
GET /projects/:id/issues/:issue_iid/closed_by
```

| Attribute   | Type    | Required | Description                          |
| ---------   | ----    | -------- | -----------                          |
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project issue   |

```bash
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by
```

Example response:

```json
[
  {
    "id": 6471,
    "iid": 6432,
    "project_id": 1,
    "title": "add a test for cgi lexer options",
    "description": "closes #11",
    "state": "opened",
    "created_at": "2017-04-06T18:33:34.168Z",
    "updated_at": "2017-04-09T20:10:24.983Z",
    "target_branch": "master",
    "source_branch": "feature.custom-highlighting",
    "upvotes": 0,
    "downvotes": 0,
    "author": {
      "name": "Administrator",
      "username": "root",
      "id": 1,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/root"
    },
    "assignee": null,
    "source_project_id": 1,
    "target_project_id": 1,
    "labels": [],
    "work_in_progress": false,
    "milestone": null,
    "merge_when_pipeline_succeeds": false,
    "merge_status": "unchecked",
    "sha": "5a62481d563af92b8e32d735f2fa63b94e806835",
    "merge_commit_sha": null,
    "user_notes_count": 1,
    "should_remove_source_branch": null,
    "force_remove_source_branch": false,
    "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/merge_requests/6432"
  }
]
```


963 964
## Comments on issues

965
Comments are done via the [notes](notes.md) resource.