issues.md 34.7 KB
Newer Older
Marin Jankovski's avatar
Marin Jankovski committed
1 2
# Issues

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's avatar
Nihad Abbasov committed
15 16
## List issues

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

```
GET /issues
jubianchi's avatar
jubianchi committed
21 22
GET /issues?state=opened
GET /issues?state=closed
jubianchi's avatar
jubianchi committed
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's avatar
Nihad Abbasov committed
30 31
```

32 33 34 35 36 37 38 39 40 41 42
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
| Attribute   | Type           | Required | Description                                                                                                                 |
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
| `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`                                                          |
| `search`    | string         | no       | Search issues against their `title` and `description`                                                                        |
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
43 44

```bash
45
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues
46
```
jubianchi's avatar
jubianchi committed
47

48
Example response:
jubianchi's avatar
jubianchi committed
49

Nihad Abbasov's avatar
Nihad Abbasov committed
50 51
```json
[
52 53 54 55 56 57
   {
      "state" : "opened",
      "description" : "Ratione dolores corrupti mollitia soluta quia.",
      "author" : {
         "state" : "active",
         "id" : 18,
58
         "web_url" : "https://gitlab.example.com/eileen.lowe",
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78
         "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,
      "assignee" : {
         "state" : "active",
         "id" : 1,
         "name" : "Administrator",
79
         "web_url" : "https://gitlab.example.com/root",
80 81 82 83 84 85 86 87
         "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,
88
      "labels" : [],
89
      "user_notes_count": 1,
90
      "due_date": "2016-07-22",
91 92
      "web_url": "http://example.com/example/example/issues/6",
      "confidential": false
93
   }
Nihad Abbasov's avatar
Nihad Abbasov committed
94 95 96
]
```

97 98 99 100 101 102 103 104 105 106 107 108 109
## 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
110
GET /groups/:id/issues?iids[]=42&iids[]=43
111
GET /groups/:id/issues?search=issue+title+or+description
112 113
```

114 115 116 117 118 119 120 121 122 123 124 125
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
| Attribute   | Type           | Required | Description                                                                                                                 |
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
| `id`        | integer        | yes      | The ID of a group                                                                                                           |
| `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`                                                                  |
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
126 127 128


```bash
129
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/4/issues
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
```

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",
151
         "web_url" : "https://gitlab.example.com/root",
152 153 154 155 156 157 158 159 160 161
         "avatar_url" : null,
         "username" : "root",
         "id" : 1,
         "name" : "Administrator"
      },
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "state" : "closed",
      "iid" : 1,
      "assignee" : {
         "avatar_url" : null,
162
         "web_url" : "https://gitlab.example.com/lennie",
163 164 165 166 167 168 169 170 171 172
         "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",
173
      "user_notes_count": 1,
174
      "due_date": null,
175 176
      "web_url": "http://example.com/example/example/issues/1",
      "confidential": false
177 178 179 180
   }
]
```

Nihad Abbasov's avatar
Nihad Abbasov committed
181 182
## List project issues

183
Get a list of a project's issues.
Nihad Abbasov's avatar
Nihad Abbasov committed
184 185 186

```
GET /projects/:id/issues
jubianchi's avatar
jubianchi committed
187 188
GET /projects/:id/issues?state=opened
GET /projects/:id/issues?state=closed
jubianchi's avatar
jubianchi committed
189 190 191
GET /projects/:id/issues?labels=foo
GET /projects/:id/issues?labels=foo,bar
GET /projects/:id/issues?labels=foo,bar&state=opened
192 193
GET /projects/:id/issues?milestone=1.0.0
GET /projects/:id/issues?milestone=1.0.0&state=opened
194
GET /projects/:id/issues?iids[]=42&iids[]=43
195
GET /projects/:id/issues?search=issue+title+or+description
Nihad Abbasov's avatar
Nihad Abbasov committed
196 197
```

198 199 200 201 202 203 204 205 206 207 208 209
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
| Attribute   | Type           | Required | Description                                                                                                                 |
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
| `id`        | integer        | yes      | The ID of a project                                                                                                         |
| `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`                                                                |
|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------|
210 211 212


```bash
213
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues
214 215 216
```

Example response:
Nihad Abbasov's avatar
Nihad Abbasov committed
217

218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
```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",
235
         "web_url" : "https://gitlab.example.com/root",
236 237 238 239 240 241 242 243 244 245
         "avatar_url" : null,
         "username" : "root",
         "id" : 1,
         "name" : "Administrator"
      },
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "state" : "closed",
      "iid" : 1,
      "assignee" : {
         "avatar_url" : null,
246
         "web_url" : "https://gitlab.example.com/lennie",
247 248 249 250 251 252 253 254 255
         "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",
256
      "created_at" : "2016-01-04T15:31:46.176Z",
257
      "user_notes_count": 1,
258
      "due_date": "2016-07-22",
259 260
      "web_url": "http://example.com/example/example/issues/1",
      "confidential": false
261 262 263
   }
]
```
264

Nihad Abbasov's avatar
Nihad Abbasov committed
265 266
## Single issue

267
Get a single project issue.
Nihad Abbasov's avatar
Nihad Abbasov committed
268 269

```
270
GET /projects/:id/issues/:issue_iid
Nihad Abbasov's avatar
Nihad Abbasov committed
271 272
```

273
|-------------+---------+----------+--------------------------------------|
274
| Attribute   | Type    | Required | Description                          |
275
|-------------+---------+----------+--------------------------------------|
276 277
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
278
|-------------+---------+----------+--------------------------------------|
Nihad Abbasov's avatar
Nihad Abbasov committed
279

280
```bash
281
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/41
282 283 284
```

Example response:
Nihad Abbasov's avatar
Nihad Abbasov committed
285 286 287

```json
{
288 289 290 291 292 293 294 295 296 297 298 299 300 301
   "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",
302
      "web_url" : "https://gitlab.example.com/root",
303 304 305 306 307 308 309 310 311 312
      "avatar_url" : null,
      "username" : "root",
      "id" : 1,
      "name" : "Administrator"
   },
   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
   "state" : "closed",
   "iid" : 1,
   "assignee" : {
      "avatar_url" : null,
313
      "web_url" : "https://gitlab.example.com/lennie",
314 315 316 317 318 319 320 321 322
      "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",
323
   "created_at" : "2016-01-04T15:31:46.176Z",
324
   "subscribed": false,
325
   "user_notes_count": 1,
326
   "due_date": null,
327 328
   "web_url": "http://example.com/example/example/issues/1",
   "confidential": false
Nihad Abbasov's avatar
Nihad Abbasov committed
329 330 331 332 333
}
```

## New issue

334
Creates a new project issue.
Nihad Abbasov's avatar
Nihad Abbasov committed
335 336 337 338 339

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

340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356
|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------|
| Attribute                                 | Type    | Required | Description                                                                                                                                          |
|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                                      | integer | yes      | The ID of a project                                                                                                                                  |
| `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`.                                                                                                 |
| `assignee_id`                             | integer | no       | The ID of a user to assign issue                                                                                                                     |
| `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`.                                                                      |
|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------|
357 358

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

362
Example response:
Nihad Abbasov's avatar
Nihad Abbasov committed
363

364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379
```json
{
   "project_id" : 4,
   "id" : 84,
   "created_at" : "2016-01-07T12:44:33.959Z",
   "iid" : 14,
   "title" : "Issues with auth",
   "state" : "opened",
   "assignee" : null,
   "labels" : [
      "bug"
   ],
   "author" : {
      "name" : "Alexandra Bashirian",
      "avatar_url" : null,
      "state" : "active",
380
      "web_url" : "https://gitlab.example.com/eileen.lowe",
381 382 383 384 385
      "id" : 18,
      "username" : "eileen.lowe"
   },
   "description" : null,
   "updated_at" : "2016-01-07T12:44:33.959Z",
386
   "milestone" : null,
387
   "subscribed" : true,
388
   "user_notes_count": 0,
389
   "due_date": null,
390 391
   "web_url": "http://example.com/example/example/issues/14",
   "confidential": false
392 393
}
```
394

Nihad Abbasov's avatar
Nihad Abbasov committed
395 396
## Edit issue

397 398 399
Updates an existing project issue. This call is also used to mark an issue as
closed.

Nihad Abbasov's avatar
Nihad Abbasov committed
400
```
401
PUT /projects/:id/issues/:issue_iid
Nihad Abbasov's avatar
Nihad Abbasov committed
402 403
```

404
|----------------+---------+----------+------------------------------------------------------------------------------------------------------------|
405
| Attribute      | Type    | Required | Description                                                                                                |
406
|----------------+---------+----------+------------------------------------------------------------------------------------------------------------|
407 408 409 410 411 412 413 414 415 416 417
| `id`           | integer | yes      | The ID of a project                                                                                        |
| `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                                                                        |
| `assignee_id`  | integer | no       | The ID of a user to assign the issue to                                                                    |
| `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`                                           |
418
|----------------+---------+----------+------------------------------------------------------------------------------------------------------------|
419 420

```bash
421
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close
422
```
Nihad Abbasov's avatar
Nihad Abbasov committed
423

424
Example response:
425

426 427 428 429 430 431 432 433 434
```json
{
   "created_at" : "2016-01-07T12:46:01.410Z",
   "author" : {
      "name" : "Alexandra Bashirian",
      "avatar_url" : null,
      "username" : "eileen.lowe",
      "id" : 18,
      "state" : "active",
435
      "web_url" : "https://gitlab.example.com/eileen.lowe"
436 437 438 439 440 441 442 443 444 445 446 447
   },
   "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,
   "assignee" : null,
448
   "milestone" : null,
449
   "subscribed" : true,
450
   "user_notes_count": 0,
451
   "due_date": "2016-07-22",
452 453
   "web_url": "http://example.com/example/example/issues/15",
   "confidential": false
454 455
}
```
456

457
## Delete an issue
458

459
Only for admins and project owners. Soft deletes the issue in question.
460 461

```
462
DELETE /projects/:id/issues/:issue_iid
463 464
```

465
|-------------+---------+----------+--------------------------------------|
466
| Attribute   | Type    | Required | Description                          |
467
|-------------+---------+----------+--------------------------------------|
468 469
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
470
|-------------+---------+----------+--------------------------------------|
471 472

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

476 477
## Move an issue

478
Moves an issue to a different project. If the target project
479 480
equals the source project or the user has insufficient permissions to move an
issue, error `400` together with an explaining error message is returned.
481

482 483 484
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.

485
```
486
POST /projects/:id/issues/:issue_iid/move
487 488
```

489
|-----------------+---------+----------+--------------------------------------|
490
| Attribute       | Type    | Required | Description                          |
491
|-----------------+---------+----------+--------------------------------------|
492 493 494
| `id`            | integer | yes      | The ID of a project                  |
| `issue_iid`     | integer | yes      | The internal ID of a project's issue |
| `to_project_id` | integer | yes      | The ID of the new project            |
495
|-----------------+---------+----------+--------------------------------------|
496 497

```bash
498
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85/move
499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520
```

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,
  "assignee": {
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
521
    "web_url": "https://gitlab.example.com/axel.block"
522 523 524 525 526 527 528
  },
  "author": {
    "name": "Kris Steuber",
    "username": "solon.cremin",
    "id": 10,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80&d=identicon",
529
    "web_url": "https://gitlab.example.com/solon.cremin"
530
  },
531
  "due_date": null,
532 533
  "web_url": "http://example.com/example/example/issues/11",
  "confidential": false
534 535 536
}
```

537 538
## Subscribe to an issue

539
Subscribes the authenticated user to an issue to receive notifications.
540 541
If the user is already subscribed to the issue, the status code `304`
is returned.
542 543

```
544
POST /projects/:id/issues/:issue_iid/subscribe
545 546
```

547
|-------------+---------+----------+--------------------------------------|
548
| Attribute   | Type    | Required | Description                          |
549
|-------------+---------+----------+--------------------------------------|
550 551
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
552
|-------------+---------+----------+--------------------------------------|
553 554

```bash
555
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe
556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577
```

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,
  "assignee": {
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
578
    "web_url": "https://gitlab.example.com/axel.block"
579 580 581 582 583 584 585
  },
  "author": {
    "name": "Kris Steuber",
    "username": "solon.cremin",
    "id": 10,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80&d=identicon",
586
    "web_url": "https://gitlab.example.com/solon.cremin"
587
  },
588
  "due_date": null,
589 590
  "web_url": "http://example.com/example/example/issues/11",
  "confidential": false
591 592 593 594 595
}
```

## Unsubscribe from an issue

596
Unsubscribes the authenticated user from the issue to not receive notifications
597 598
from it. If the user is not subscribed to the issue, the
status code `304` is returned.
599 600

```
601
POST /projects/:id/issues/:issue_iid/unsubscribe
602 603
```

604
|-------------+---------+----------+--------------------------------------|
605
| Attribute   | Type    | Required | Description                          |
606
|-------------+---------+----------+--------------------------------------|
607 608
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
609
|-------------+---------+----------+--------------------------------------|
610 611

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

615 616
## Create a todo

617
Manually creates a todo for the current user on an issue. If
618 619 620 621
there already exists a todo for the user on that issue, status code `304` is
returned.

```
622
POST /projects/:id/issues/:issue_iid/todo
623 624
```

625
|-------------+---------+----------+--------------------------------------|
626
| Attribute   | Type    | Required | Description                          |
627
|-------------+---------+----------+--------------------------------------|
628 629
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
630
|-------------+---------+----------+--------------------------------------|
631 632

```bash
633
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/todo
634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653
```

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",
654
    "web_url": "https://gitlab.example.com/root"
655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684
  },
  "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
    },
    "assignee": {
      "name": "Jarret O'Keefe",
      "username": "francisca",
      "id": 14,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon",
685
      "web_url": "https://gitlab.example.com/francisca"
686 687 688 689 690 691 692
    },
    "author": {
      "name": "Maxie Medhurst",
      "username": "craig_rutherford",
      "id": 12,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
693
      "web_url": "https://gitlab.example.com/craig_rutherford"
694 695 696 697
    },
    "subscribed": true,
    "user_notes_count": 7,
    "upvotes": 0,
698 699
    "downvotes": 0,
    "due_date": null,
700 701
    "web_url": "http://example.com/example/example/issues/110",
    "confidential": false
702 703 704 705 706 707 708 709
  },
  "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"
}
```

710 711 712 713 714
## Set a time estimate for an issue

Sets an estimated time of work for this issue.

```
715
POST /projects/:id/issues/:issue_iid/time_estimate
716 717
```

718
|-------------+---------+----------+------------------------------------------|
719
| Attribute   | Type    | Required | Description                              |
720
|-------------+---------+----------+------------------------------------------|
721 722 723
| `id`        | integer | yes      | The ID of a project                      |
| `issue_iid` | integer | yes      | The internal ID of a project's issue     |
| `duration`  | string  | yes      | The duration in human format. e.g: 3h30m |
724
|-------------+---------+----------+------------------------------------------|
725 726

```bash
727
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745
```

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.

```
746
POST /projects/:id/issues/:issue_iid/reset_time_estimate
747 748
```

749
|-------------+---------+----------+--------------------------------------|
750
| Attribute   | Type    | Required | Description                          |
751
|-------------+---------+----------+--------------------------------------|
752 753
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
754
|-------------+---------+----------+--------------------------------------|
755 756

```bash
757
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate
758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775
```

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

```
776
POST /projects/:id/issues/:issue_iid/add_spent_time
777 778
```

779
|-------------+---------+----------+------------------------------------------|
780
| Attribute   | Type    | Required | Description                              |
781
|-------------+---------+----------+------------------------------------------|
782 783 784
| `id`        | integer | yes      | The ID of a project                      |
| `issue_iid` | integer | yes      | The internal ID of a project's issue     |
| `duration`  | string  | yes      | The duration in human format. e.g: 3h30m |
785
|-------------+---------+----------+------------------------------------------|
786 787

```bash
788
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h
789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806
```

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.

```
807
POST /projects/:id/issues/:issue_iid/reset_spent_time
808 809
```

810
|-------------+---------+----------+--------------------------------------|
811
| Attribute   | Type    | Required | Description                          |
812
|-------------+---------+----------+--------------------------------------|
813 814
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
815
|-------------+---------+----------+--------------------------------------|
816 817

```bash
818
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time
819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834
```

Example response:

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

## Get time tracking stats

```
835
GET /projects/:id/issues/:issue_iid/time_stats
836 837
```

838
|-------------+---------+----------+--------------------------------------|
839
| Attribute   | Type    | Required | Description                          |
840
|-------------+---------+----------+--------------------------------------|
841 842
| `id`        | integer | yes      | The ID of a project                  |
| `issue_iid` | integer | yes      | The internal ID of a project's issue |
843
|-------------+---------+----------+--------------------------------------|
844 845

```bash
846
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats
847 848 849 850 851 852 853 854 855 856 857 858 859
```

Example response:

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

860 861
## Comments on issues

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