1--- 2stage: Plan 3group: Project Management 4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 5--- 6 7# Issues API **(FREE)** 8 9Interact with [GitLab Issues](../user/project/issues/index.md) using the REST API. 10 11If a user is not a member of a private project, a `GET` 12request on that project results in a `404` status code. 13 14## Issues pagination 15 16By default, `GET` requests return 20 results at a time because the API results 17are paginated. 18 19Read more on [pagination](index.md#pagination). 20 21WARNING: 22The `reference` attribute in responses is deprecated in favor of `references`. 23[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.6. 24 25NOTE: 26The `references.relative` attribute is relative to the group or project of the issue being requested. 27When an issue is fetched from its project, the `relative` format is the same as the `short` format. 28When requested across groups or projects, it's expected to be the same as the `full` format. 29 30## List issues 31 32> The `weight` property moved to GitLab Premium in 13.9. 33 34Get all issues the authenticated user has access to. By default it 35returns only issues created by the current user. To get all issues, 36use parameter `scope=all`. 37 38```plaintext 39GET /issues 40GET /issues?assignee_id=5 41GET /issues?author_id=5 42GET /issues?confidential=true 43GET /issues?iids[]=42&iids[]=43 44GET /issues?labels=foo 45GET /issues?labels=foo,bar 46GET /issues?labels=foo,bar&state=opened 47GET /issues?milestone=1.0.0 48GET /issues?milestone=1.0.0&state=opened 49GET /issues?my_reaction_emoji=star 50GET /issues?search=foo&in=title 51GET /issues?state=closed 52GET /issues?state=opened 53``` 54 55| Attribute | Type | Required | Description | 56| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | 57| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | 58| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | 59| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | 60| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | 61| `confidential` | boolean | no | Filter confidential or public issues. | 62| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 63| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 64| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | 65| `iids[]` | integer array | no | Return only the issues having the given `iid` | 66| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | 67| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | 68| `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | 69| `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | 70| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | 71| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. Using `None` or `Any` will be [deprecated in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/336044). Please use `milestone_id` attribute instead. `milestone` and `milestone_id` are mutually exclusive. | 72| `milestone_id` | string | no | Returns issues assigned to milestones with a given timebox value (`None`, `Any`, `Upcoming`, and `Started`). `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. `Upcoming` lists all issues assigned to milestones due in the future. `Started` lists all issues assigned to open, started milestones. `milestone` and `milestone_id` are mutually exclusive. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335939) in GitLab 14.3)_ | 73| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | 74| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197170) in GitLab 13.0)_ | 75| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, `milestone_id` and `weight`. | 76| `order_by` | string | no | Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, `updated_at`, or `weight` fields. Default is `created_at`. | 77| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | 78| `search` | string | no | Search issues against their `title` and `description` | 79| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | 80| `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | 81| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 82| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 83| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | 84| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7| 85 86```shell 87curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues" 88``` 89 90Example response: 91 92```json 93[ 94 { 95 "state" : "opened", 96 "description" : "Ratione dolores corrupti mollitia soluta quia.", 97 "author" : { 98 "state" : "active", 99 "id" : 18, 100 "web_url" : "https://gitlab.example.com/eileen.lowe", 101 "name" : "Alexandra Bashirian", 102 "avatar_url" : null, 103 "username" : "eileen.lowe" 104 }, 105 "milestone" : { 106 "project_id" : 1, 107 "description" : "Ducimus nam enim ex consequatur cumque ratione.", 108 "state" : "closed", 109 "due_date" : null, 110 "iid" : 2, 111 "created_at" : "2016-01-04T15:31:39.996Z", 112 "title" : "v4.0", 113 "id" : 17, 114 "updated_at" : "2016-01-04T15:31:39.996Z" 115 }, 116 "project_id" : 1, 117 "assignees" : [{ 118 "state" : "active", 119 "id" : 1, 120 "name" : "Administrator", 121 "web_url" : "https://gitlab.example.com/root", 122 "avatar_url" : null, 123 "username" : "root" 124 }], 125 "assignee" : { 126 "state" : "active", 127 "id" : 1, 128 "name" : "Administrator", 129 "web_url" : "https://gitlab.example.com/root", 130 "avatar_url" : null, 131 "username" : "root" 132 }, 133 "type" : "ISSUE", 134 "updated_at" : "2016-01-04T15:31:51.081Z", 135 "closed_at" : null, 136 "closed_by" : null, 137 "id" : 76, 138 "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.", 139 "created_at" : "2016-01-04T15:31:51.081Z", 140 "moved_to_id" : null, 141 "iid" : 6, 142 "labels" : ["foo", "bar"], 143 "upvotes": 4, 144 "downvotes": 0, 145 "merge_requests_count": 0, 146 "user_notes_count": 1, 147 "due_date": "2016-07-22", 148 "web_url": "http://gitlab.example.com/my-group/my-project/issues/6", 149 "references": { 150 "short": "#6", 151 "relative": "my-group/my-project#6", 152 "full": "my-group/my-project#6" 153 }, 154 "time_stats": { 155 "time_estimate": 0, 156 "total_time_spent": 0, 157 "human_time_estimate": null, 158 "human_total_time_spent": null 159 }, 160 "has_tasks": true, 161 "task_status": "10 of 15 tasks completed", 162 "confidential": false, 163 "discussion_locked": false, 164 "issue_type": "issue", 165 "_links":{ 166 "self":"http://gitlab.example.com/api/v4/projects/1/issues/76", 167 "notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes", 168 "award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji", 169 "project":"http://gitlab.example.com/api/v4/projects/1" 170 }, 171 "task_completion_status":{ 172 "count":0, 173 "completed_count":0 174 } 175 } 176] 177``` 178 179Issues created by users on GitLab Premium or higher include the `weight` property: 180 181```json 182[ 183 { 184 "state" : "opened", 185 "description" : "Ratione dolores corrupti mollitia soluta quia.", 186 "weight": null, 187 ... 188 } 189] 190``` 191 192Issues created by users on GitLab Premium or higher include the `epic` property: 193 194```json 195{ 196 "project_id" : 4, 197 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 198 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 199 "epic": { 200 "id" : 42, 201 "iid" : 5, 202 "title": "My epic epic", 203 "url" : "/groups/h5bp/-/epics/5", 204 "group_id": 8 205 }, 206 ... 207} 208``` 209 210Issues created by users on GitLab Ultimate include the `health_status` property: 211 212```json 213[ 214 { 215 "state" : "opened", 216 "description" : "Ratione dolores corrupti mollitia soluta quia.", 217 "health_status": "on_track", 218 ... 219 } 220] 221``` 222 223WARNING: 224The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform 225to the GitLab EE API. 226 227WARNING: 228The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 229Please use `iid` of the `epic` attribute instead. 230 231NOTE: 232The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. 233This value is only present for issues closed after GitLab 10.6 and if the user account 234that closed the issue still exists. 235 236## List group issues 237 238> The `weight` property moved to GitLab Premium in 13.9. 239 240Get a list of a group's issues. 241 242If the group is private, credentials need to be provided for authorization. 243The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). 244 245```plaintext 246GET /groups/:id/issues 247GET /groups/:id/issues?assignee_id=5 248GET /groups/:id/issues?author_id=5 249GET /groups/:id/issues?confidential=true 250GET /groups/:id/issues?iids[]=42&iids[]=43 251GET /groups/:id/issues?labels=foo 252GET /groups/:id/issues?labels=foo,bar 253GET /groups/:id/issues?labels=foo,bar&state=opened 254GET /groups/:id/issues?milestone=1.0.0 255GET /groups/:id/issues?milestone=1.0.0&state=opened 256GET /groups/:id/issues?my_reaction_emoji=star 257GET /groups/:id/issues?search=issue+title+or+description 258GET /groups/:id/issues?state=closed 259GET /groups/:id/issues?state=opened 260``` 261 262| Attribute | Type | Required | Description | 263| ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | 264| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | 265| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | 266| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | 267| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | 268| `confidential` | boolean | no | Filter confidential or public issues. | 269| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 270| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 271| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | 272| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | 273| `iids[]` | integer array | no | Return only the issues having the given `iid` | 274| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | 275| `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | 276| `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | 277| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | 278| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | 279| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | 280| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785) in GitLab 12.8)_ | 281| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | 282| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | 283| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | 284| `search` | string | no | Search group issues against their `title` and `description` | 285| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | 286| `state` | string | no | Return all issues or just those that are `opened` or `closed` | 287| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 288| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 289| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | 290| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | 291 292```shell 293curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/issues" 294``` 295 296Example response: 297 298```json 299[ 300 { 301 "project_id" : 4, 302 "milestone" : { 303 "due_date" : null, 304 "project_id" : 4, 305 "state" : "closed", 306 "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", 307 "iid" : 3, 308 "id" : 11, 309 "title" : "v3.0", 310 "created_at" : "2016-01-04T15:31:39.788Z", 311 "updated_at" : "2016-01-04T15:31:39.788Z" 312 }, 313 "author" : { 314 "state" : "active", 315 "web_url" : "https://gitlab.example.com/root", 316 "avatar_url" : null, 317 "username" : "root", 318 "id" : 1, 319 "name" : "Administrator" 320 }, 321 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 322 "state" : "closed", 323 "iid" : 1, 324 "assignees" : [{ 325 "avatar_url" : null, 326 "web_url" : "https://gitlab.example.com/lennie", 327 "state" : "active", 328 "username" : "lennie", 329 "id" : 9, 330 "name" : "Dr. Luella Kovacek" 331 }], 332 "assignee" : { 333 "avatar_url" : null, 334 "web_url" : "https://gitlab.example.com/lennie", 335 "state" : "active", 336 "username" : "lennie", 337 "id" : 9, 338 "name" : "Dr. Luella Kovacek" 339 }, 340 "type" : "ISSUE", 341 "labels" : ["foo", "bar"], 342 "upvotes": 4, 343 "downvotes": 0, 344 "merge_requests_count": 0, 345 "id" : 41, 346 "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", 347 "updated_at" : "2016-01-04T15:31:46.176Z", 348 "created_at" : "2016-01-04T15:31:46.176Z", 349 "closed_at" : null, 350 "closed_by" : null, 351 "user_notes_count": 1, 352 "due_date": null, 353 "web_url": "http://gitlab.example.com/my-group/my-project/issues/1", 354 "references": { 355 "short": "#1", 356 "relative": "my-project#1", 357 "full": "my-group/my-project#1" 358 }, 359 "time_stats": { 360 "time_estimate": 0, 361 "total_time_spent": 0, 362 "human_time_estimate": null, 363 "human_total_time_spent": null 364 }, 365 "has_tasks": true, 366 "task_status": "10 of 15 tasks completed", 367 "confidential": false, 368 "discussion_locked": false, 369 "issue_type": "issue", 370 "_links":{ 371 "self":"http://gitlab.example.com/api/v4/projects/4/issues/41", 372 "notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes", 373 "award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji", 374 "project":"http://gitlab.example.com/api/v4/projects/4" 375 }, 376 "task_completion_status":{ 377 "count":0, 378 "completed_count":0 379 } 380 } 381] 382``` 383 384Issues created by users on GitLab Premium or higher include the `weight` property: 385 386```json 387[ 388 { 389 "project_id" : 4, 390 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 391 "weight": null, 392 ... 393 } 394] 395``` 396 397Issues created by users on GitLab Premium or higher include the `epic` property: 398 399```json 400{ 401 "project_id" : 4, 402 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 403 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 404 "epic": { 405 "id" : 42, 406 "iid" : 5, 407 "title": "My epic epic", 408 "url" : "/groups/h5bp/-/epics/5", 409 "group_id": 8 410 }, 411 ... 412} 413``` 414 415Issues created by users on GitLab Ultimate include the `health_status` property: 416 417```json 418[ 419 { 420 "project_id" : 4, 421 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 422 "health_status": "at_risk", 423 ... 424 } 425] 426``` 427 428WARNING: 429The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. 430 431WARNING: 432The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 433Please use `iid` of the `epic` attribute instead. 434 435NOTE: 436The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. 437This value is only present for issues closed after GitLab 10.6 and if the user account that closed 438the issue still exists. 439 440## List project issues 441 442> The `weight` property moved to GitLab Premium in 13.9. 443 444Get a list of a project's issues. 445 446If the project is private, you need to provide credentials to authorize. 447The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). 448 449```plaintext 450GET /projects/:id/issues 451GET /projects/:id/issues?assignee_id=5 452GET /projects/:id/issues?author_id=5 453GET /projects/:id/issues?confidential=true 454GET /projects/:id/issues?iids[]=42&iids[]=43 455GET /projects/:id/issues?labels=foo 456GET /projects/:id/issues?labels=foo,bar 457GET /projects/:id/issues?labels=foo,bar&state=opened 458GET /projects/:id/issues?milestone=1.0.0 459GET /projects/:id/issues?milestone=1.0.0&state=opened 460GET /projects/:id/issues?my_reaction_emoji=star 461GET /projects/:id/issues?search=issue+title+or+description 462GET /projects/:id/issues?state=closed 463GET /projects/:id/issues?state=opened 464``` 465 466| Attribute | Type | Required | Description | 467| ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | 468| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | 469| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | 470| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | 471| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | 472| `confidential` | boolean | no | Filter confidential or public issues. | 473| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 474| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 475| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | 476| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 477| `iids[]` | integer array | no | Return only the issues having the given `iid` | 478| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | 479| `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | 480| `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | 481| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | 482| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | 483| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | 484| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | 485| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | 486| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | 487| `search` | string | no | Search project issues against their `title` and `description` | 488| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | 489| `state` | string | no | Return all issues or just those that are `opened` or `closed` | 490| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 491| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | 492| `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | 493| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | 494 495```shell 496curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues" 497``` 498 499Example response: 500 501```json 502[ 503 { 504 "project_id" : 4, 505 "milestone" : { 506 "due_date" : null, 507 "project_id" : 4, 508 "state" : "closed", 509 "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", 510 "iid" : 3, 511 "id" : 11, 512 "title" : "v3.0", 513 "created_at" : "2016-01-04T15:31:39.788Z", 514 "updated_at" : "2016-01-04T15:31:39.788Z" 515 }, 516 "author" : { 517 "state" : "active", 518 "web_url" : "https://gitlab.example.com/root", 519 "avatar_url" : null, 520 "username" : "root", 521 "id" : 1, 522 "name" : "Administrator" 523 }, 524 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 525 "state" : "closed", 526 "iid" : 1, 527 "assignees" : [{ 528 "avatar_url" : null, 529 "web_url" : "https://gitlab.example.com/lennie", 530 "state" : "active", 531 "username" : "lennie", 532 "id" : 9, 533 "name" : "Dr. Luella Kovacek" 534 }], 535 "assignee" : { 536 "avatar_url" : null, 537 "web_url" : "https://gitlab.example.com/lennie", 538 "state" : "active", 539 "username" : "lennie", 540 "id" : 9, 541 "name" : "Dr. Luella Kovacek" 542 }, 543 "type" : "ISSUE", 544 "labels" : ["foo", "bar"], 545 "upvotes": 4, 546 "downvotes": 0, 547 "merge_requests_count": 0, 548 "id" : 41, 549 "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", 550 "updated_at" : "2016-01-04T15:31:46.176Z", 551 "created_at" : "2016-01-04T15:31:46.176Z", 552 "closed_at" : "2016-01-05T15:31:46.176Z", 553 "closed_by" : { 554 "state" : "active", 555 "web_url" : "https://gitlab.example.com/root", 556 "avatar_url" : null, 557 "username" : "root", 558 "id" : 1, 559 "name" : "Administrator" 560 }, 561 "user_notes_count": 1, 562 "due_date": "2016-07-22", 563 "web_url": "http://gitlab.example.com/my-group/my-project/issues/1", 564 "references": { 565 "short": "#1", 566 "relative": "#1", 567 "full": "my-group/my-project#1" 568 }, 569 "time_stats": { 570 "time_estimate": 0, 571 "total_time_spent": 0, 572 "human_time_estimate": null, 573 "human_total_time_spent": null 574 }, 575 "has_tasks": true, 576 "task_status": "10 of 15 tasks completed", 577 "confidential": false, 578 "discussion_locked": false, 579 "issue_type": "issue", 580 "_links":{ 581 "self":"http://gitlab.example.com/api/v4/projects/4/issues/41", 582 "notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes", 583 "award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji", 584 "project":"http://gitlab.example.com/api/v4/projects/4" 585 }, 586 "task_completion_status":{ 587 "count":0, 588 "completed_count":0 589 } 590 } 591] 592``` 593 594Issues created by users on GitLab Premium or higher include the `weight` property: 595 596```json 597[ 598 { 599 "project_id" : 4, 600 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 601 "weight": null, 602 ... 603 } 604] 605``` 606 607Issues created by users on GitLab Premium or higher include the `epic` property: 608 609```json 610{ 611 "project_id" : 4, 612 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 613 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 614 "epic": { 615 "id" : 42, 616 "iid" : 5, 617 "title": "My epic epic", 618 "url" : "/groups/h5bp/-/epics/5", 619 "group_id": 8 620 }, 621 ... 622} 623``` 624 625Issues created by users on GitLab Ultimate include the `health_status` property: 626 627```json 628[ 629 { 630 "project_id" : 4, 631 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 632 "health_status": "at_risk", 633 ... 634 } 635] 636``` 637 638WARNING: 639The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. 640 641WARNING: 642The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 643Please use `iid` of the `epic` attribute instead. 644 645NOTE: 646The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed 647the issue still exists. 648 649## Single issue 650 651Only for administrators. Get a single issue. 652 653The preferred way to do this is by using [personal access tokens](../user/profile/personal_access_tokens.md). 654 655```plaintext 656GET /issues/:id 657``` 658 659| Attribute | Type | Required | Description | 660|-------------|---------|----------|--------------------------------------| 661| `id` | integer | yes | The ID of the issue | 662 663```shell 664curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues/41" 665``` 666 667Example response: 668 669```json 670{ 671 "id": 1, 672 "milestone": { 673 "due_date": null, 674 "project_id": 4, 675 "state": "closed", 676 "description": "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", 677 "iid": 3, 678 "id": 11, 679 "title": "v3.0", 680 "created_at": "2016-01-04T15:31:39.788Z", 681 "updated_at": "2016-01-04T15:31:39.788Z", 682 "closed_at": "2016-01-05T15:31:46.176Z" 683 }, 684 "author": { 685 "state": "active", 686 "web_url": "https://gitlab.example.com/root", 687 "avatar_url": null, 688 "username": "root", 689 "id": 1, 690 "name": "Administrator" 691 }, 692 "description": "Omnis vero earum sunt corporis dolor et placeat.", 693 "state": "closed", 694 "iid": 1, 695 "assignees": [ 696 { 697 "avatar_url": null, 698 "web_url": "https://gitlab.example.com/lennie", 699 "state": "active", 700 "username": "lennie", 701 "id": 9, 702 "name": "Dr. Luella Kovacek" 703 } 704 ], 705 "assignee": { 706 "avatar_url": null, 707 "web_url": "https://gitlab.example.com/lennie", 708 "state": "active", 709 "username": "lennie", 710 "id": 9, 711 "name": "Dr. Luella Kovacek" 712 }, 713 "type": "ISSUE", 714 "labels": [], 715 "upvotes": 4, 716 "downvotes": 0, 717 "merge_requests_count": 0, 718 "title": "Ut commodi ullam eos dolores perferendis nihil sunt.", 719 "updated_at": "2016-01-04T15:31:46.176Z", 720 "created_at": "2016-01-04T15:31:46.176Z", 721 "closed_at": null, 722 "closed_by": null, 723 "subscribed": false, 724 "user_notes_count": 1, 725 "due_date": null, 726 "web_url": "http://example.com/my-group/my-project/issues/1", 727 "references": { 728 "short": "#1", 729 "relative": "#1", 730 "full": "my-group/my-project#1" 731 }, 732 "time_stats": { 733 "time_estimate": 0, 734 "total_time_spent": 0, 735 "human_time_estimate": null, 736 "human_total_time_spent": null 737 }, 738 "confidential": false, 739 "discussion_locked": false, 740 "issue_type": "issue", 741 "task_completion_status": { 742 "count": 0, 743 "completed_count": 0 744 }, 745 "weight": null, 746 "has_tasks": false, 747 "_links": { 748 "self": "http://gitlab.example:3000/api/v4/projects/1/issues/1", 749 "notes": "http://gitlab.example:3000/api/v4/projects/1/issues/1/notes", 750 "award_emoji": "http://gitlab.example:3000/api/v4/projects/1/issues/1/award_emoji", 751 "project": "http://gitlab.example:3000/api/v4/projects/1" 752 }, 753 "moved_to_id": null, 754 "service_desk_reply_to": "service.desk@gitlab.com" 755} 756``` 757 758Issues created by users on GitLab Premium or higher include the `weight` property: 759 760```json 761{ 762 "project_id" : 4, 763 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 764 "weight": null, 765 ... 766} 767``` 768 769Issues created by users on GitLab Premium or higher include the `epic` property: 770 771```json 772{ 773 "project_id" : 4, 774 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 775 "epic": { 776 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 777 "epic": { 778 "id" : 42, 779 "iid" : 5, 780 "title": "My epic epic", 781 "url" : "/groups/h5bp/-/epics/5", 782 "group_id": 8 783 }, 784 ... 785} 786``` 787 788Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` 789property: 790 791```json 792[ 793 { 794 "project_id" : 4, 795 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 796 "health_status": "on_track", 797 ... 798 } 799] 800``` 801 802WARNING: 803The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform 804to the GitLab EE API. 805 806WARNING: 807The `epic_iid` attribute is deprecated, and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 808Please use `iid` of the `epic` attribute instead. 809 810NOTE: 811The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. 812This value is only present for issues closed after GitLab 10.6 and if the user account 813that closed the issue still exists. 814 815## Single project issue 816 817Get a single project issue. 818 819If the project is private or the issue is confidential, you need to provide credentials to authorize. 820The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). 821 822```plaintext 823GET /projects/:id/issues/:issue_iid 824``` 825 826| Attribute | Type | Required | Description | 827|-------------|---------|----------|--------------------------------------| 828| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 829| `issue_iid` | integer | yes | The internal ID of a project's issue | 830 831```shell 832curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/41" 833``` 834 835Example response: 836 837```json 838{ 839 "project_id" : 4, 840 "milestone" : { 841 "due_date" : null, 842 "project_id" : 4, 843 "state" : "closed", 844 "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", 845 "iid" : 3, 846 "id" : 11, 847 "title" : "v3.0", 848 "created_at" : "2016-01-04T15:31:39.788Z", 849 "updated_at" : "2016-01-04T15:31:39.788Z", 850 "closed_at" : "2016-01-05T15:31:46.176Z" 851 }, 852 "author" : { 853 "state" : "active", 854 "web_url" : "https://gitlab.example.com/root", 855 "avatar_url" : null, 856 "username" : "root", 857 "id" : 1, 858 "name" : "Administrator" 859 }, 860 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 861 "state" : "closed", 862 "iid" : 1, 863 "assignees" : [{ 864 "avatar_url" : null, 865 "web_url" : "https://gitlab.example.com/lennie", 866 "state" : "active", 867 "username" : "lennie", 868 "id" : 9, 869 "name" : "Dr. Luella Kovacek" 870 }], 871 "assignee" : { 872 "avatar_url" : null, 873 "web_url" : "https://gitlab.example.com/lennie", 874 "state" : "active", 875 "username" : "lennie", 876 "id" : 9, 877 "name" : "Dr. Luella Kovacek" 878 }, 879 "type" : "ISSUE", 880 "labels" : [], 881 "upvotes": 4, 882 "downvotes": 0, 883 "merge_requests_count": 0, 884 "id" : 41, 885 "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", 886 "updated_at" : "2016-01-04T15:31:46.176Z", 887 "created_at" : "2016-01-04T15:31:46.176Z", 888 "closed_at" : null, 889 "closed_by" : null, 890 "subscribed": false, 891 "user_notes_count": 1, 892 "due_date": null, 893 "web_url": "http://gitlab.example.com/my-group/my-project/issues/1", 894 "references": { 895 "short": "#1", 896 "relative": "#1", 897 "full": "my-group/my-project#1" 898 }, 899 "time_stats": { 900 "time_estimate": 0, 901 "total_time_spent": 0, 902 "human_time_estimate": null, 903 "human_total_time_spent": null 904 }, 905 "confidential": false, 906 "discussion_locked": false, 907 "issue_type": "issue", 908 "_links": { 909 "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", 910 "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", 911 "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji", 912 "project": "http://gitlab.example.com/api/v4/projects/1" 913 }, 914 "task_completion_status":{ 915 "count":0, 916 "completed_count":0 917 } 918} 919``` 920 921Issues created by users on GitLab Premium or higher include the `weight` property: 922 923```json 924{ 925 "project_id" : 4, 926 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 927 "weight": null, 928 ... 929} 930``` 931 932Issues created by users on GitLab Premium or higher include the `epic` property: 933 934```json 935{ 936 "project_id" : 4, 937 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 938 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 939 "epic": { 940 "id" : 42, 941 "iid" : 5, 942 "title": "My epic epic", 943 "url" : "/groups/h5bp/-/epics/5", 944 "group_id": 8 945 }, 946 ... 947} 948``` 949 950Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` 951property: 952 953```json 954[ 955 { 956 "project_id" : 4, 957 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 958 "health_status": "on_track", 959 ... 960 } 961] 962``` 963 964WARNING: 965The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. 966 967WARNING: 968The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 969Please use `iid` of the `epic` attribute instead. 970 971NOTE: 972The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed 973the issue still exists. 974 975## New issue 976 977> The `weight` property moved to GitLab Premium in 13.9. 978 979Creates a new project issue. 980 981```plaintext 982POST /projects/:id/issues 983``` 984 985| Attribute | Type | Required | Description | 986|-------------------------------------------|----------------|----------|--------------| 987| `assignee_id` | integer | no | The ID of the user to assign the issue to. Only appears on GitLab Free. | 988| `assignee_ids` **(PREMIUM)** | integer array | no | The IDs of the users to assign the issue to. | 989| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | 990| `created_at` | string | no | When the issue was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. | 991| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | 992| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This fills out the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | 993| `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | 994| `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | 995| `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | 996| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 997| `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | 998| `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | 999| `labels` | string | no | Comma-separated label names for an issue | 1000| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these values take precedence over the default values.| 1001| `milestone_id` | integer | no | The global ID of a milestone to assign issue. To find the `milestone_id` associated with a milestone, view an issue with the milestone assigned and [use the API](#single-project-issue) to retrieve the issue's details. | 1002| `title` | string | yes | The title of an issue | 1003| `weight` **(PREMIUM)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | 1004 1005```shell 1006curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug" 1007``` 1008 1009Example response: 1010 1011```json 1012{ 1013 "project_id" : 4, 1014 "id" : 84, 1015 "created_at" : "2016-01-07T12:44:33.959Z", 1016 "iid" : 14, 1017 "title" : "Issues with auth", 1018 "state" : "opened", 1019 "assignees" : [], 1020 "assignee" : null, 1021 "type" : "ISSUE", 1022 "labels" : [ 1023 "bug" 1024 ], 1025 "upvotes": 4, 1026 "downvotes": 0, 1027 "merge_requests_count": 0, 1028 "author" : { 1029 "name" : "Alexandra Bashirian", 1030 "avatar_url" : null, 1031 "state" : "active", 1032 "web_url" : "https://gitlab.example.com/eileen.lowe", 1033 "id" : 18, 1034 "username" : "eileen.lowe" 1035 }, 1036 "description" : null, 1037 "updated_at" : "2016-01-07T12:44:33.959Z", 1038 "closed_at" : null, 1039 "closed_by" : null, 1040 "milestone" : null, 1041 "subscribed" : true, 1042 "user_notes_count": 0, 1043 "due_date": null, 1044 "web_url": "http://gitlab.example.com/my-group/my-project/issues/14", 1045 "references": { 1046 "short": "#14", 1047 "relative": "#14", 1048 "full": "my-group/my-project#14" 1049 }, 1050 "time_stats": { 1051 "time_estimate": 0, 1052 "total_time_spent": 0, 1053 "human_time_estimate": null, 1054 "human_total_time_spent": null 1055 }, 1056 "confidential": false, 1057 "discussion_locked": false, 1058 "issue_type": "issue", 1059 "_links": { 1060 "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", 1061 "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", 1062 "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji", 1063 "project": "http://gitlab.example.com/api/v4/projects/1" 1064 }, 1065 "task_completion_status":{ 1066 "count":0, 1067 "completed_count":0 1068 } 1069} 1070``` 1071 1072Issues created by users on GitLab Premium or higher include the `weight` property: 1073 1074```json 1075{ 1076 "project_id" : 4, 1077 "description" : null, 1078 "weight": null, 1079 ... 1080} 1081``` 1082 1083Issues created by users on GitLab Premium or higher include the `epic` property: 1084 1085```json 1086{ 1087 "project_id" : 4, 1088 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 1089 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 1090 "epic": { 1091 "id" : 42, 1092 "iid" : 5, 1093 "title": "My epic epic", 1094 "url" : "/groups/h5bp/-/epics/5", 1095 "group_id": 8 1096 }, 1097 ... 1098} 1099``` 1100 1101Issues created by users on GitLab Ultimate include the `health_status` property: 1102 1103```json 1104[ 1105 { 1106 "project_id" : 4, 1107 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 1108 "health_status": "on_track", 1109 ... 1110 } 1111] 1112``` 1113 1114WARNING: 1115The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. 1116 1117WARNING: 1118The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 1119Please use `iid` of the `epic` attribute instead. 1120 1121NOTE: 1122The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed 1123the issue still exists. 1124 1125## Rate limits 1126 1127To help avoid abuse, users can be limited to a specific number of `Create` requests per minute. 1128See [Issues rate limits](../user/admin_area/settings/rate_limit_on_issues_creation.md). 1129 1130## Edit issue 1131 1132> The `weight` property moved to GitLab Premium in 13.9. 1133 1134Updates an existing project issue. This call is also used to mark an issue as 1135closed. 1136 1137At least one of the following parameters is required for the request to be successful: 1138 1139- `:assignee_id` 1140- `:assignee_ids` 1141- `:confidential` 1142- `:created_at` 1143- `:description` 1144- `:discussion_locked` 1145- `:due_date` 1146- `:issue_type` 1147- `:labels` 1148- `:milestone_id` 1149- `:state_event` 1150- `:title` 1151 1152```plaintext 1153PUT /projects/:id/issues/:issue_iid 1154``` 1155 1156| Attribute | Type | Required | Description | 1157|----------------|---------|----------|------------------------------------------------------------------------------------------------------------| 1158| `add_labels` | string | no | Comma-separated label names to add to an issue. | 1159| `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | 1160| `confidential` | boolean | no | Updates an issue to be confidential | 1161| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | 1162| `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | 1163| `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | 1164| `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | 1165| `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | 1166| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 1167| `issue_iid` | integer | yes | The internal ID of a project's issue | 1168| `issue_type` | string | no | Updates the type of issue. One of `issue`, `incident`, or `test_case`. | 1169| `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | 1170| `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| 1171| `remove_labels`| string | no | Comma-separated label names to remove from an issue. | 1172| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | 1173| `title` | string | no | The title of an issue | 1174| `updated_at` | string | no | When the issue was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.| 1175| `weight` **(PREMIUM)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | 1176 1177```shell 1178curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close" 1179``` 1180 1181Example response: 1182 1183```json 1184{ 1185 "created_at" : "2016-01-07T12:46:01.410Z", 1186 "author" : { 1187 "name" : "Alexandra Bashirian", 1188 "avatar_url" : null, 1189 "username" : "eileen.lowe", 1190 "id" : 18, 1191 "state" : "active", 1192 "web_url" : "https://gitlab.example.com/eileen.lowe" 1193 }, 1194 "state" : "closed", 1195 "title" : "Issues with auth", 1196 "project_id" : 4, 1197 "description" : null, 1198 "updated_at" : "2016-01-07T12:55:16.213Z", 1199 "closed_at" : "2016-01-08T12:55:16.213Z", 1200 "closed_by" : { 1201 "state" : "active", 1202 "web_url" : "https://gitlab.example.com/root", 1203 "avatar_url" : null, 1204 "username" : "root", 1205 "id" : 1, 1206 "name" : "Administrator" 1207 }, 1208 "iid" : 15, 1209 "labels" : [ 1210 "bug" 1211 ], 1212 "upvotes": 4, 1213 "downvotes": 0, 1214 "merge_requests_count": 0, 1215 "id" : 85, 1216 "assignees" : [], 1217 "assignee" : null, 1218 "milestone" : null, 1219 "subscribed" : true, 1220 "user_notes_count": 0, 1221 "due_date": "2016-07-22", 1222 "web_url": "http://gitlab.example.com/my-group/my-project/issues/15", 1223 "references": { 1224 "short": "#15", 1225 "relative": "#15", 1226 "full": "my-group/my-project#15" 1227 }, 1228 "time_stats": { 1229 "time_estimate": 0, 1230 "total_time_spent": 0, 1231 "human_time_estimate": null, 1232 "human_total_time_spent": null 1233 }, 1234 "confidential": false, 1235 "discussion_locked": false, 1236 "issue_type": "issue", 1237 "_links": { 1238 "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", 1239 "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", 1240 "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji", 1241 "project": "http://gitlab.example.com/api/v4/projects/1" 1242 }, 1243 "task_completion_status":{ 1244 "count":0, 1245 "completed_count":0 1246 } 1247} 1248``` 1249 1250Issues created by users on GitLab Premium or higher include the `weight` property: 1251 1252```json 1253{ 1254 "project_id" : 4, 1255 "description" : null, 1256 "weight": null, 1257 ... 1258} 1259``` 1260 1261Issues created by users on GitLab Premium or higher include the `epic` property: 1262 1263```json 1264{ 1265 "project_id" : 4, 1266 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 1267 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 1268 "epic": { 1269 "id" : 42, 1270 "iid" : 5, 1271 "title": "My epic epic", 1272 "url" : "/groups/h5bp/-/epics/5", 1273 "group_id": 8 1274 }, 1275 ... 1276} 1277``` 1278 1279Issues created by users on GitLab Ultimate include the `health_status` property: 1280 1281```json 1282[ 1283 { 1284 "project_id" : 4, 1285 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 1286 "health_status": "on_track", 1287 ... 1288 } 1289] 1290``` 1291 1292NOTE: 1293The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed 1294the issue still exists. 1295 1296WARNING: 1297The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 1298Please use `iid` of the `epic` attribute instead. 1299 1300WARNING: 1301`assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. 1302 1303## Delete an issue 1304 1305Only for administrators and project owners. Deletes an issue. 1306 1307```plaintext 1308DELETE /projects/:id/issues/:issue_iid 1309``` 1310 1311| Attribute | Type | Required | Description | 1312|-------------|---------|----------|--------------------------------------| 1313| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 1314| `issue_iid` | integer | yes | The internal ID of a project's issue | 1315 1316```shell 1317curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85" 1318``` 1319 1320## Reorder an issue 1321 1322> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211864) in GitLab 13.2. 1323 1324Reorders an issue, you can see the results when sorting issues manually 1325 1326```plaintext 1327PUT /projects/:id/issues/:issue_iid/reorder 1328``` 1329 1330| Attribute | Type | Required | Description | 1331|-------------|---------|----------|--------------------------------------| 1332| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 1333| `issue_iid` | integer | yes | The internal ID of the project's issue | 1334| `move_after_id` | integer | no | The ID of a project's issue that should be placed after this issue | 1335| `move_before_id` | integer | no | The ID of a project's issue that should be placed before this issue | 1336 1337```shell 1338curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85/reorder?move_after_id=51&move_before_id=92" 1339``` 1340 1341## Move an issue 1342 1343Moves an issue to a different project. If the target project 1344is the source project or the user has insufficient permissions, 1345an error message with status code `400` is returned. 1346 1347If a given label or milestone with the same name also exists in the target 1348project, it's then assigned to the issue being moved. 1349 1350```plaintext 1351POST /projects/:id/issues/:issue_iid/move 1352``` 1353 1354| Attribute | Type | Required | Description | 1355|-----------------|---------|----------|--------------------------------------| 1356| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 1357| `issue_iid` | integer | yes | The internal ID of a project's issue | 1358| `to_project_id` | integer | yes | The ID of the new project | 1359 1360```shell 1361curl --header "PRIVATE-TOKEN: <your_access_token>" --form to_project_id=5 "https://gitlab.example.com/api/v4/projects/4/issues/85/move" 1362``` 1363 1364Example response: 1365 1366```json 1367{ 1368 "id": 92, 1369 "iid": 11, 1370 "project_id": 5, 1371 "title": "Sit voluptas tempora quisquam aut doloribus et.", 1372 "description": "Repellat voluptas quibusdam voluptatem exercitationem.", 1373 "state": "opened", 1374 "created_at": "2016-04-05T21:41:45.652Z", 1375 "updated_at": "2016-04-07T12:20:17.596Z", 1376 "closed_at": null, 1377 "closed_by": null, 1378 "labels": [], 1379 "upvotes": 4, 1380 "downvotes": 0, 1381 "merge_requests_count": 0, 1382 "milestone": null, 1383 "assignees": [{ 1384 "name": "Miss Monserrate Beier", 1385 "username": "axel.block", 1386 "id": 12, 1387 "state": "active", 1388 "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", 1389 "web_url": "https://gitlab.example.com/axel.block" 1390 }], 1391 "assignee": { 1392 "name": "Miss Monserrate Beier", 1393 "username": "axel.block", 1394 "id": 12, 1395 "state": "active", 1396 "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", 1397 "web_url": "https://gitlab.example.com/axel.block" 1398 }, 1399 "type" : "ISSUE", 1400 "author": { 1401 "name": "Kris Steuber", 1402 "username": "solon.cremin", 1403 "id": 10, 1404 "state": "active", 1405 "avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80&d=identicon", 1406 "web_url": "https://gitlab.example.com/solon.cremin" 1407 }, 1408 "due_date": null, 1409 "web_url": "http://gitlab.example.com/my-group/my-project/issues/11", 1410 "references": { 1411 "short": "#11", 1412 "relative": "#11", 1413 "full": "my-group/my-project#11" 1414 }, 1415 "time_stats": { 1416 "time_estimate": 0, 1417 "total_time_spent": 0, 1418 "human_time_estimate": null, 1419 "human_total_time_spent": null 1420 }, 1421 "confidential": false, 1422 "discussion_locked": false, 1423 "issue_type": "issue", 1424 "_links": { 1425 "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", 1426 "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", 1427 "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji", 1428 "project": "http://gitlab.example.com/api/v4/projects/1" 1429 }, 1430 "task_completion_status":{ 1431 "count":0, 1432 "completed_count":0 1433 } 1434} 1435``` 1436 1437Issues created by users on GitLab Premium or higher include the `weight` property: 1438 1439```json 1440{ 1441 "project_id": 5, 1442 "description": "Repellat voluptas quibusdam voluptatem exercitationem.", 1443 "weight": null, 1444 ... 1445} 1446``` 1447 1448Issues created by users on GitLab Premium or higher include the `epic` property: 1449 1450```json 1451{ 1452 "project_id" : 4, 1453 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 1454 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 1455 "epic": { 1456 "id" : 42, 1457 "iid" : 5, 1458 "title": "My epic epic", 1459 "url" : "/groups/h5bp/-/epics/5", 1460 "group_id": 8 1461 }, 1462 ... 1463} 1464``` 1465 1466Issues created by users on GitLab Ultimate include the `health_status` property: 1467 1468```json 1469[ 1470 { 1471 "project_id" : 4, 1472 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 1473 "health_status": "on_track", 1474 ... 1475 } 1476] 1477``` 1478 1479WARNING: 1480The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. 1481 1482WARNING: 1483The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 1484Please use `iid` of the `epic` attribute instead. 1485 1486NOTE: 1487The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed 1488the issue still exists. 1489 1490## Clone an issue 1491 1492Clone the issue to given project. If the user has insufficient permissions, 1493an error message with status code `400` is returned. 1494 1495Copies as much data as possible as long as the target project contains equivalent labels, milestones, 1496and so on. 1497 1498```plaintext 1499POST /projects/:id/issues/:issue_iid/clone 1500``` 1501 1502| Attribute | Type | Required | Description | 1503| --------------- | -------------- | ---------------------- | --------------------------------- | 1504| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | 1505| `issue_iid` | integer | **{check-circle}** Yes | Internal ID of a project's issue. | 1506| `to_project_id` | integer | **{check-circle}** Yes | ID of the new project. | 1507| `with_notes` | boolean | **{dotted-circle}** No | Clone the issue with [notes](notes.md). Default is `false`. | 1508 1509```shell 1510curl --request POST \ 1511--header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/1/clone?with_notes=true&to_project_id=6" 1512``` 1513 1514Example response: 1515 1516```json 1517{ 1518 "id":290, 1519 "iid":1, 1520 "project_id":143, 1521 "title":"foo", 1522 "description":"closed", 1523 "state":"opened", 1524 "created_at":"2021-09-14T22:24:11.696Z", 1525 "updated_at":"2021-09-14T22:24:11.696Z", 1526 "closed_at":null, 1527 "closed_by":null, 1528 "labels":[ 1529 1530 ], 1531 "milestone":null, 1532 "assignees":[ 1533 { 1534 "id":179, 1535 "name":"John Doe2", 1536 "username":"john", 1537 "state":"active", 1538 "avatar_url":"https://www.gravatar.com/avatar/10fc7f102be8de7657fb4d80898bbfe3?s=80\u0026d=identicon", 1539 "web_url":"https://gitlab.example.com/john" 1540 } 1541 ], 1542 "author":{ 1543 "id":179, 1544 "name":"John Doe2", 1545 "username":"john", 1546 "state":"active", 1547 "avatar_url":"https://www.gravatar.com/avatar/10fc7f102be8de7657fb4d80898bbfe3?s=80\u0026d=identicon", 1548 "web_url":"https://gitlab.example.com/john" 1549 }, 1550 "type":"ISSUE", 1551 "assignee":{ 1552 "id":179, 1553 "name":"John Doe2", 1554 "username":"john", 1555 "state":"active", 1556 "avatar_url":"https://www.gravatar.com/avatar/10fc7f102be8de7657fb4d80898bbfe3?s=80\u0026d=identicon", 1557 "web_url":"https://gitlab.example.com/john" 1558 }, 1559 "user_notes_count":1, 1560 "merge_requests_count":0, 1561 "upvotes":0, 1562 "downvotes":0, 1563 "due_date":null, 1564 "confidential":false, 1565 "discussion_locked":null, 1566 "issue_type":"issue", 1567 "web_url":"https://gitlab.example.com/namespace1/project2/-/issues/1", 1568 "time_stats":{ 1569 "time_estimate":0, 1570 "total_time_spent":0, 1571 "human_time_estimate":null, 1572 "human_total_time_spent":null 1573 }, 1574 "task_completion_status":{ 1575 "count":0, 1576 "completed_count":0 1577 }, 1578 "blocking_issues_count":0, 1579 "has_tasks":false, 1580 "_links":{ 1581 "self":"https://gitlab.example.com/api/v4/projects/143/issues/1", 1582 "notes":"https://gitlab.example.com/api/v4/projects/143/issues/1/notes", 1583 "award_emoji":"https://gitlab.example.com/api/v4/projects/143/issues/1/award_emoji", 1584 "project":"https://gitlab.example.com/api/v4/projects/143" 1585 }, 1586 "references":{ 1587 "short":"#1", 1588 "relative":"#1", 1589 "full":"namespace1/project2#1" 1590 }, 1591 "subscribed":true, 1592 "moved_to_id":null, 1593 "service_desk_reply_to":null 1594} 1595``` 1596 1597## Subscribe to an issue 1598 1599Subscribes the authenticated user to an issue to receive notifications. 1600If the user is already subscribed to the issue, the status code `304` 1601is returned. 1602 1603```plaintext 1604POST /projects/:id/issues/:issue_iid/subscribe 1605``` 1606 1607| Attribute | Type | Required | Description | 1608|-------------|---------|----------|--------------------------------------| 1609| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 1610| `issue_iid` | integer | yes | The internal ID of a project's issue | 1611 1612```shell 1613curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe" 1614``` 1615 1616Example response: 1617 1618```json 1619{ 1620 "id": 92, 1621 "iid": 11, 1622 "project_id": 5, 1623 "title": "Sit voluptas tempora quisquam aut doloribus et.", 1624 "description": "Repellat voluptas quibusdam voluptatem exercitationem.", 1625 "state": "opened", 1626 "created_at": "2016-04-05T21:41:45.652Z", 1627 "updated_at": "2016-04-07T12:20:17.596Z", 1628 "closed_at": null, 1629 "closed_by": null, 1630 "labels": [], 1631 "upvotes": 4, 1632 "downvotes": 0, 1633 "merge_requests_count": 0, 1634 "milestone": null, 1635 "assignees": [{ 1636 "name": "Miss Monserrate Beier", 1637 "username": "axel.block", 1638 "id": 12, 1639 "state": "active", 1640 "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", 1641 "web_url": "https://gitlab.example.com/axel.block" 1642 }], 1643 "assignee": { 1644 "name": "Miss Monserrate Beier", 1645 "username": "axel.block", 1646 "id": 12, 1647 "state": "active", 1648 "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", 1649 "web_url": "https://gitlab.example.com/axel.block" 1650 }, 1651 "type" : "ISSUE", 1652 "author": { 1653 "name": "Kris Steuber", 1654 "username": "solon.cremin", 1655 "id": 10, 1656 "state": "active", 1657 "avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80&d=identicon", 1658 "web_url": "https://gitlab.example.com/solon.cremin" 1659 }, 1660 "due_date": null, 1661 "web_url": "http://gitlab.example.com/my-group/my-project/issues/11", 1662 "references": { 1663 "short": "#11", 1664 "relative": "#11", 1665 "full": "my-group/my-project#11" 1666 }, 1667 "time_stats": { 1668 "time_estimate": 0, 1669 "total_time_spent": 0, 1670 "human_time_estimate": null, 1671 "human_total_time_spent": null 1672 }, 1673 "confidential": false, 1674 "discussion_locked": false, 1675 "issue_type": "issue", 1676 "_links": { 1677 "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", 1678 "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", 1679 "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji", 1680 "project": "http://gitlab.example.com/api/v4/projects/1" 1681 }, 1682 "task_completion_status":{ 1683 "count":0, 1684 "completed_count":0 1685 } 1686} 1687``` 1688 1689Issues created by users on GitLab Premium or higher include the `weight` property: 1690 1691```json 1692{ 1693 "project_id": 5, 1694 "description": "Repellat voluptas quibusdam voluptatem exercitationem.", 1695 "weight": null, 1696 ... 1697} 1698``` 1699 1700Issues created by users on GitLab Premium or higher include the `epic` property: 1701 1702```json 1703{ 1704 "project_id" : 4, 1705 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 1706 "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute 1707 "epic": { 1708 "id" : 42, 1709 "iid" : 5, 1710 "title": "My epic epic", 1711 "url" : "/groups/h5bp/-/epics/5", 1712 "group_id": 8 1713 }, 1714 ... 1715} 1716``` 1717 1718Issues created by users on GitLab Ultimate include the `health_status` property: 1719 1720```json 1721[ 1722 { 1723 "project_id" : 4, 1724 "description" : "Omnis vero earum sunt corporis dolor et placeat.", 1725 "health_status": "on_track", 1726 ... 1727 } 1728] 1729``` 1730 1731WARNING: 1732The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. 1733 1734WARNING: 1735The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. 1736Please use `iid` of the `epic` attribute instead. 1737 1738NOTE: 1739The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed 1740the issue still exists. 1741 1742## Unsubscribe from an issue 1743 1744Unsubscribes the authenticated user from the issue to not receive notifications 1745from it. If the user is not subscribed to the issue, the 1746status code `304` is returned. 1747 1748```plaintext 1749POST /projects/:id/issues/:issue_iid/unsubscribe 1750``` 1751 1752| Attribute | Type | Required | Description | 1753|-------------|---------|----------|--------------------------------------| 1754| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 1755| `issue_iid` | integer | yes | The internal ID of a project's issue | 1756 1757```shell 1758curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe" 1759``` 1760 1761Example response: 1762 1763```json 1764{ 1765 "id": 93, 1766 "iid": 12, 1767 "project_id": 5, 1768 "title": "Incidunt et rerum ea expedita iure quibusdam.", 1769 "description": "Et cumque architecto sed aut ipsam.", 1770 "state": "opened", 1771 "created_at": "2016-04-05T21:41:45.217Z", 1772 "updated_at": "2016-04-07T13:02:37.905Z", 1773 "labels": [], 1774 "upvotes": 4, 1775 "downvotes": 0, 1776 "merge_requests_count": 0, 1777 "milestone": null, 1778 "assignee": { 1779 "name": "Edwardo Grady", 1780 "username": "keyon", 1781 "id": 21, 1782 "state": "active", 1783 "avatar_url": "http://www.gravatar.com/avatar/3e6f06a86cf27fa8b56f3f74f7615987?s=80&d=identicon", 1784 "web_url": "https://gitlab.example.com/keyon" 1785 }, 1786 "type" : "ISSUE", 1787 "closed_at": null, 1788 "closed_by": null, 1789 "author": { 1790 "name": "Vivian Hermann", 1791 "username": "orville", 1792 "id": 11, 1793 "state": "active", 1794 "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon", 1795 "web_url": "https://gitlab.example.com/orville" 1796 }, 1797 "subscribed": false, 1798 "due_date": null, 1799 "web_url": "http://gitlab.example.com/my-group/my-project/issues/12", 1800 "references": { 1801 "short": "#12", 1802 "relative": "#12", 1803 "full": "my-group/my-project#12" 1804 }, 1805 "confidential": false, 1806 "discussion_locked": false, 1807 "issue_type": "issue", 1808 "task_completion_status":{ 1809 "count":0, 1810 "completed_count":0 1811 } 1812} 1813``` 1814 1815## Create a to-do item 1816 1817Manually creates a to-do item for the current user on an issue. If 1818there already exists a to-do item for the user on that issue, status code `304` is 1819returned. 1820 1821```plaintext 1822POST /projects/:id/issues/:issue_iid/todo 1823``` 1824 1825| Attribute | Type | Required | Description | 1826|-------------|---------|----------|--------------------------------------| 1827| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 1828| `issue_iid` | integer | yes | The internal ID of a project's issue | 1829 1830```shell 1831curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/todo" 1832``` 1833 1834Example response: 1835 1836```json 1837{ 1838 "id": 112, 1839 "project": { 1840 "id": 5, 1841 "name": "GitLab CI/CD", 1842 "name_with_namespace": "GitLab Org / GitLab CI/CD", 1843 "path": "gitlab-ci", 1844 "path_with_namespace": "gitlab-org/gitlab-ci" 1845 }, 1846 "author": { 1847 "name": "Administrator", 1848 "username": "root", 1849 "id": 1, 1850 "state": "active", 1851 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 1852 "web_url": "https://gitlab.example.com/root" 1853 }, 1854 "action_name": "marked", 1855 "target_type": "Issue", 1856 "target": { 1857 "id": 93, 1858 "iid": 10, 1859 "project_id": 5, 1860 "title": "Vel voluptas atque dicta mollitia adipisci qui at.", 1861 "description": "Tempora laboriosam sint magni sed voluptas similique.", 1862 "state": "closed", 1863 "created_at": "2016-06-17T07:47:39.486Z", 1864 "updated_at": "2016-07-01T11:09:13.998Z", 1865 "labels": [], 1866 "milestone": { 1867 "id": 26, 1868 "iid": 1, 1869 "project_id": 5, 1870 "title": "v0.0", 1871 "description": "Accusantium nostrum rerum quae quia quis nesciunt suscipit id.", 1872 "state": "closed", 1873 "created_at": "2016-06-17T07:47:33.832Z", 1874 "updated_at": "2016-06-17T07:47:33.832Z", 1875 "due_date": null 1876 }, 1877 "assignees": [{ 1878 "name": "Jarret O'Keefe", 1879 "username": "francisca", 1880 "id": 14, 1881 "state": "active", 1882 "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon", 1883 "web_url": "https://gitlab.example.com/francisca" 1884 }], 1885 "assignee": { 1886 "name": "Jarret O'Keefe", 1887 "username": "francisca", 1888 "id": 14, 1889 "state": "active", 1890 "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon", 1891 "web_url": "https://gitlab.example.com/francisca" 1892 }, 1893 "type" : "ISSUE", 1894 "author": { 1895 "name": "Maxie Medhurst", 1896 "username": "craig_rutherford", 1897 "id": 12, 1898 "state": "active", 1899 "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon", 1900 "web_url": "https://gitlab.example.com/craig_rutherford" 1901 }, 1902 "subscribed": true, 1903 "user_notes_count": 7, 1904 "upvotes": 0, 1905 "downvotes": 0, 1906 "merge_requests_count": 0, 1907 "due_date": null, 1908 "web_url": "http://gitlab.example.com/my-group/my-project/issues/10", 1909 "references": { 1910 "short": "#10", 1911 "relative": "#10", 1912 "full": "my-group/my-project#10" 1913 }, 1914 "confidential": false, 1915 "discussion_locked": false, 1916 "issue_type": "issue", 1917 "task_completion_status":{ 1918 "count":0, 1919 "completed_count":0 1920 } 1921 }, 1922 "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/issues/10", 1923 "body": "Vel voluptas atque dicta mollitia adipisci qui at.", 1924 "state": "pending", 1925 "created_at": "2016-07-01T11:09:13.992Z" 1926} 1927``` 1928 1929WARNING: 1930The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. 1931 1932NOTE: 1933The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed 1934the issue still exists. 1935 1936## Promote an issue to an epic **(PREMIUM)** 1937 1938Promotes an issue to an epic by adding a comment with the `/promote` 1939[quick action](../user/project/quick_actions.md). 1940 1941To learn more about promoting issues to epics, visit [Manage epics](../user/group/epics/manage_epics.md#promote-an-issue-to-an-epic). 1942 1943```plaintext 1944POST /projects/:id/issues/:issue_iid/notes 1945``` 1946 1947Supported attributes: 1948 1949| Attribute | Type | Required | Description | 1950| :---------- | :------------- | :------- | :---------- | 1951| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 1952| `issue_iid` | integer | yes | The internal ID of a project's issue | 1953| `body` | String | yes | The content of a note. Must contain `/promote` at the start of a new line. | 1954 1955Example request: 1956 1957```shell 1958curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=Lets%20promote%20this%20to%20an%20epic%0A%0A%2Fpromote" 1959``` 1960 1961Example response: 1962 1963```json 1964{ 1965 "id":699, 1966 "type":null, 1967 "body":"Lets promote this to an epic", 1968 "attachment":null, 1969 "author": { 1970 "id":1, 1971 "name":"Alexandra Bashirian", 1972 "username":"eileen.lowe", 1973 "state":"active", 1974 "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 1975 "web_url":"https://gitlab.example.com/eileen.lowe" 1976 }, 1977 "created_at":"2020-12-03T12:27:17.844Z", 1978 "updated_at":"2020-12-03T12:27:17.844Z", 1979 "system":false, 1980 "noteable_id":461, 1981 "noteable_type":"Issue", 1982 "resolvable":false, 1983 "confidential":false, 1984 "noteable_iid":33, 1985 "commands_changes": { 1986 "promote_to_epic":true 1987 } 1988} 1989``` 1990 1991## Set a time estimate for an issue 1992 1993Sets an estimated time of work for this issue. 1994 1995```plaintext 1996POST /projects/:id/issues/:issue_iid/time_estimate 1997``` 1998 1999| Attribute | Type | Required | Description | 2000|-------------|---------|----------|------------------------------------------| 2001| `duration` | string | yes | The duration in human format. e.g: 3h30m | 2002| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2003| `issue_iid` | integer | yes | The internal ID of a project's issue | 2004 2005```shell 2006curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m" 2007``` 2008 2009Example response: 2010 2011```json 2012{ 2013 "human_time_estimate": "3h 30m", 2014 "human_total_time_spent": null, 2015 "time_estimate": 12600, 2016 "total_time_spent": 0 2017} 2018``` 2019 2020## Reset the time estimate for an issue 2021 2022Resets the estimated time for this issue to 0 seconds. 2023 2024```plaintext 2025POST /projects/:id/issues/:issue_iid/reset_time_estimate 2026``` 2027 2028| Attribute | Type | Required | Description | 2029|-------------|---------|----------|--------------------------------------| 2030| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2031| `issue_iid` | integer | yes | The internal ID of a project's issue | 2032 2033```shell 2034curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate" 2035``` 2036 2037Example response: 2038 2039```json 2040{ 2041 "human_time_estimate": null, 2042 "human_total_time_spent": null, 2043 "time_estimate": 0, 2044 "total_time_spent": 0 2045} 2046``` 2047 2048## Add spent time for an issue 2049 2050Adds spent time for this issue 2051 2052```plaintext 2053POST /projects/:id/issues/:issue_iid/add_spent_time 2054``` 2055 2056| Attribute | Type | Required | Description | 2057|-------------|---------|----------|------------------------------------------| 2058| `duration` | string | yes | The duration in human format. e.g: 3h30m | 2059| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2060| `issue_iid` | integer | yes | The internal ID of a project's issue | 2061| `summary` | string | no | A summary of how the time was spent | 2062 2063```shell 2064curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h" 2065``` 2066 2067Example response: 2068 2069```json 2070{ 2071 "human_time_estimate": null, 2072 "human_total_time_spent": "1h", 2073 "time_estimate": 0, 2074 "total_time_spent": 3600 2075} 2076``` 2077 2078## Reset spent time for an issue 2079 2080Resets the total spent time for this issue to 0 seconds. 2081 2082```plaintext 2083POST /projects/:id/issues/:issue_iid/reset_spent_time 2084``` 2085 2086| Attribute | Type | Required | Description | 2087|-------------|---------|----------|--------------------------------------| 2088| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2089| `issue_iid` | integer | yes | The internal ID of a project's issue | 2090 2091```shell 2092curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time" 2093``` 2094 2095Example response: 2096 2097```json 2098{ 2099 "human_time_estimate": null, 2100 "human_total_time_spent": null, 2101 "time_estimate": 0, 2102 "total_time_spent": 0 2103} 2104``` 2105 2106## Get time tracking stats 2107 2108If the project is private or the issue is confidential, you need to provide credentials to authorize. 2109The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). 2110 2111```plaintext 2112GET /projects/:id/issues/:issue_iid/time_stats 2113``` 2114 2115| Attribute | Type | Required | Description | 2116|-------------|---------|----------|--------------------------------------| 2117| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2118| `issue_iid` | integer | yes | The internal ID of a project's issue | 2119 2120```shell 2121curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats" 2122``` 2123 2124Example response: 2125 2126```json 2127{ 2128 "human_time_estimate": "2h", 2129 "human_total_time_spent": "1h", 2130 "time_estimate": 7200, 2131 "total_time_spent": 3600 2132} 2133``` 2134 2135## List merge requests related to issue 2136 2137Get all the merge requests that are related to the issue. 2138 2139If the project is private or the issue is confidential, you need to provide credentials to authorize. 2140The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). 2141 2142```plaintext 2143GET /projects/:id/issues/:issue_iid/related_merge_requests 2144``` 2145 2146| Attribute | Type | Required | Description | 2147|-------------|---------|----------|--------------------------------------| 2148| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2149| `issue_iid` | integer | yes | The internal ID of a project's issue | 2150 2151```shell 2152curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests" 2153``` 2154 2155Example response: 2156 2157```json 2158[ 2159 { 2160 "id": 29, 2161 "iid": 11, 2162 "project_id": 1, 2163 "title": "Provident eius eos blanditiis consequatur neque odit.", 2164 "description": "Ut consequatur ipsa aspernatur quisquam voluptatum fugit. Qui harum corporis quo fuga ut incidunt veritatis. Autem necessitatibus et harum occaecati nihil ea.\r\n\r\ntwitter/flight#8", 2165 "state": "opened", 2166 "created_at": "2018-09-18T14:36:15.510Z", 2167 "updated_at": "2018-09-19T07:45:13.089Z", 2168 "closed_by": null, 2169 "closed_at": null, 2170 "target_branch": "v2.x", 2171 "source_branch": "so_long_jquery", 2172 "user_notes_count": 9, 2173 "upvotes": 0, 2174 "downvotes": 0, 2175 "author": { 2176 "id": 14, 2177 "name": "Verna Hills", 2178 "username": "lawanda_reinger", 2179 "state": "active", 2180 "avatar_url": "https://www.gravatar.com/avatar/de68a91aeab1cff563795fb98a0c2cc0?s=80&d=identicon", 2181 "web_url": "https://gitlab.example.com/lawanda_reinger" 2182 }, 2183 "assignee": { 2184 "id": 19, 2185 "name": "Jody Baumbach", 2186 "username": "felipa.kuvalis", 2187 "state": "active", 2188 "avatar_url": "https://www.gravatar.com/avatar/6541fc75fc4e87e203529bd275fafd07?s=80&d=identicon", 2189 "web_url": "https://gitlab.example.com/felipa.kuvalis" 2190 }, 2191 "source_project_id": 1, 2192 "target_project_id": 1, 2193 "labels": [], 2194 "draft": false, 2195 "work_in_progress": false, 2196 "milestone": { 2197 "id": 27, 2198 "iid": 2, 2199 "project_id": 1, 2200 "title": "v1.0", 2201 "description": "Et tenetur voluptatem minima doloribus vero dignissimos vitae.", 2202 "state": "active", 2203 "created_at": "2018-09-18T14:35:44.353Z", 2204 "updated_at": "2018-09-18T14:35:44.353Z", 2205 "due_date": null, 2206 "start_date": null, 2207 "web_url": "https://gitlab.example.com/twitter/flight/milestones/2" 2208 }, 2209 "merge_when_pipeline_succeeds": false, 2210 "merge_status": "cannot_be_merged", 2211 "sha": "3b7b528e9353295c1c125dad281ac5b5deae5f12", 2212 "merge_commit_sha": null, 2213 "squash_commit_sha": null, 2214 "discussion_locked": null, 2215 "should_remove_source_branch": null, 2216 "force_remove_source_branch": false, 2217 "reference": "!11", 2218 "web_url": "https://gitlab.example.com/twitter/flight/merge_requests/4", 2219 "references": { 2220 "short": "!4", 2221 "relative": "!4", 2222 "full": "twitter/flight!4" 2223 }, 2224 "time_stats": { 2225 "time_estimate": 0, 2226 "total_time_spent": 0, 2227 "human_time_estimate": null, 2228 "human_total_time_spent": null 2229 }, 2230 "squash": false, 2231 "task_completion_status": { 2232 "count": 0, 2233 "completed_count": 0 2234 }, 2235 "changes_count": "10", 2236 "latest_build_started_at": "2018-12-05T01:16:41.723Z", 2237 "latest_build_finished_at": "2018-12-05T02:35:54.046Z", 2238 "first_deployed_to_production_at": null, 2239 "pipeline": { 2240 "id": 38980952, 2241 "sha": "81c6a84c7aebd45a1ac2c654aa87f11e32338e0a", 2242 "ref": "test-branch", 2243 "status": "success", 2244 "web_url": "https://gitlab.com/gitlab-org/gitlab/pipelines/38980952" 2245 }, 2246 "head_pipeline": { 2247 "id": 38980952, 2248 "sha": "81c6a84c7aebd45a1ac2c654aa87f11e32338e0a", 2249 "ref": "test-branch", 2250 "status": "success", 2251 "web_url": "https://gitlab.example.com/twitter/flight/pipelines/38980952", 2252 "before_sha": "3c738a37eb23cf4c0ed0d45d6ddde8aad4a8da51", 2253 "tag": false, 2254 "yaml_errors": null, 2255 "user": { 2256 "id": 19, 2257 "name": "Jody Baumbach", 2258 "username": "felipa.kuvalis", 2259 "state": "active", 2260 "avatar_url": "https://www.gravatar.com/avatar/6541fc75fc4e87e203529bd275fafd07?s=80&d=identicon", 2261 "web_url": "https://gitlab.example.com/felipa.kuvalis" 2262 }, 2263 "created_at": "2018-12-05T01:16:13.342Z", 2264 "updated_at": "2018-12-05T02:35:54.086Z", 2265 "started_at": "2018-12-05T01:16:41.723Z", 2266 "finished_at": "2018-12-05T02:35:54.046Z", 2267 "committed_at": null, 2268 "duration": 4436, 2269 "coverage": "46.68", 2270 "detailed_status": { 2271 "icon": "status_warning", 2272 "text": "passed", 2273 "label": "passed with warnings", 2274 "group": "success-with-warnings", 2275 "tooltip": "passed", 2276 "has_details": true, 2277 "details_path": "/twitter/flight/pipelines/38", 2278 "illustration": null, 2279 "favicon": "https://gitlab.example.com/assets/ci_favicons/favicon_status_success-8451333011eee8ce9f2ab25dc487fe24a8758c694827a582f17f42b0a90446a2.png" 2280 } 2281 }, 2282 "diff_refs": { 2283 "base_sha": "d052d768f0126e8cddf80afd8b1eb07f406a3fcb", 2284 "head_sha": "81c6a84c7aebd45a1ac2c654aa87f11e32338e0a", 2285 "start_sha": "d052d768f0126e8cddf80afd8b1eb07f406a3fcb" 2286 }, 2287 "merge_error": null, 2288 "user": { 2289 "can_merge": true 2290 } 2291 } 2292] 2293``` 2294 2295## List merge requests that close a particular issue on merge 2296 2297Get all merge requests that close a particular issue when merged. 2298 2299If the project is private or the issue is confidential, you need to provide credentials to authorize. 2300The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). 2301 2302```plaintext 2303GET /projects/:id/issues/:issue_iid/closed_by 2304``` 2305 2306| Attribute | Type | Required | Description | 2307| ----------- | ---------------| -------- | ---------------------------------- | 2308| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2309| `issue_iid` | integer | yes | The internal ID of a project issue | 2310 2311```shell 2312curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by" 2313``` 2314 2315Example response: 2316 2317```json 2318[ 2319 { 2320 "id": 6471, 2321 "iid": 6432, 2322 "project_id": 1, 2323 "title": "add a test for cgi lexer options", 2324 "description": "closes #11", 2325 "state": "opened", 2326 "created_at": "2017-04-06T18:33:34.168Z", 2327 "updated_at": "2017-04-09T20:10:24.983Z", 2328 "target_branch": "master", 2329 "source_branch": "feature.custom-highlighting", 2330 "upvotes": 0, 2331 "downvotes": 0, 2332 "author": { 2333 "name": "Administrator", 2334 "username": "root", 2335 "id": 1, 2336 "state": "active", 2337 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 2338 "web_url": "https://gitlab.example.com/root" 2339 }, 2340 "assignee": null, 2341 "source_project_id": 1, 2342 "target_project_id": 1, 2343 "closed_at": null, 2344 "closed_by": null, 2345 "labels": [], 2346 "draft": false, 2347 "work_in_progress": false, 2348 "milestone": null, 2349 "merge_when_pipeline_succeeds": false, 2350 "merge_status": "unchecked", 2351 "sha": "5a62481d563af92b8e32d735f2fa63b94e806835", 2352 "merge_commit_sha": null, 2353 "squash_commit_sha": null, 2354 "user_notes_count": 1, 2355 "should_remove_source_branch": null, 2356 "force_remove_source_branch": false, 2357 "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/merge_requests/6432", 2358 "reference": "!6432", 2359 "references": { 2360 "short": "!6432", 2361 "relative": "!6432", 2362 "full": "gitlab-org/gitlab-test!6432" 2363 }, 2364 "time_stats": { 2365 "time_estimate": 0, 2366 "total_time_spent": 0, 2367 "human_time_estimate": null, 2368 "human_total_time_spent": null 2369 } 2370 } 2371] 2372``` 2373 2374## Participants on issues 2375 2376If the project is private or the issue is confidential, you need to provide credentials to authorize. 2377The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). 2378 2379```plaintext 2380GET /projects/:id/issues/:issue_iid/participants 2381``` 2382 2383| Attribute | Type | Required | Description | 2384|-------------|---------|----------|--------------------------------------| 2385| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2386| `issue_iid` | integer | yes | The internal ID of a project's issue | 2387 2388```shell 2389curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/participants" 2390``` 2391 2392Example response: 2393 2394```json 2395[ 2396 { 2397 "id": 1, 2398 "name": "John Doe1", 2399 "username": "user1", 2400 "state": "active", 2401 "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon", 2402 "web_url": "http://gitlab.example.com/user1" 2403 }, 2404 { 2405 "id": 5, 2406 "name": "John Doe5", 2407 "username": "user5", 2408 "state": "active", 2409 "avatar_url": "http://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80&d=identicon", 2410 "web_url": "http://gitlab.example.com/user5" 2411 } 2412] 2413``` 2414 2415## Comments on issues 2416 2417Comments are done via the [notes](notes.md) resource. 2418 2419## Get user agent details 2420 2421Available only for administrators. 2422 2423```plaintext 2424GET /projects/:id/issues/:issue_iid/user_agent_detail 2425``` 2426 2427| Attribute | Type | Required | Description | 2428|-------------|---------|----------|--------------------------------------| 2429| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2430| `issue_iid` | integer | yes | The internal ID of a project's issue | 2431 2432```shell 2433curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/user_agent_detail" 2434``` 2435 2436Example response: 2437 2438```json 2439{ 2440 "user_agent": "AppleWebKit/537.36", 2441 "ip_address": "127.0.0.1", 2442 "akismet_submitted": false 2443} 2444``` 2445 2446## List issue state events 2447 2448To track which state was set, who did it, and when it happened, check out 2449[Resource state events API](resource_state_events.md#issues). 2450 2451## Upload metric image 2452 2453Available only for Incident issues. 2454 2455```plaintext 2456POST /projects/:id/issues/:issue_iid/metric_images 2457``` 2458 2459| Attribute | Type | Required | Description | 2460|-------------|---------|----------|--------------------------------------| 2461| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2462| `issue_iid` | integer | yes | The internal ID of a project's issue | 2463| `file` | file | yes | The image file to be uploaded | 2464| `url` | string | no | The URL to view more metric information | 2465 2466```shell 2467curl --header "PRIVATE-TOKEN: <your_access_token>" --form 'file=@/path/to/file.png' \ 2468--form 'url=http://example.com' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" 2469``` 2470 2471Example response: 2472 2473```json 2474{ 2475 "id": 23, 2476 "created_at": "2020-11-13T00:06:18.084Z", 2477 "filename": "file.png", 2478 "file_path": "/uploads/-/system/issuable_metric_image/file/23/file.png", 2479 "url": "http://example.com" 2480} 2481``` 2482 2483## List metric images 2484 2485Available only for Incident issues. 2486 2487```plaintext 2488GET /projects/:id/issues/:issue_iid/metric_images 2489``` 2490 2491| Attribute | Type | Required | Description | 2492|-------------|---------|----------|--------------------------------------| 2493| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2494| `issue_iid` | integer | yes | The internal ID of a project's issue | 2495 2496```shell 2497curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" 2498``` 2499 2500Example response: 2501 2502```json 2503[ 2504 { 2505 "id": 17, 2506 "created_at": "2020-11-12T20:07:58.156Z", 2507 "filename": "sample_2054", 2508 "file_path": "/uploads/-/system/issuable_metric_image/file/17/sample_2054.png", 2509 "url": "example.com/metric" 2510 }, 2511 { 2512 "id": 18, 2513 "created_at": "2020-11-12T20:14:26.441Z", 2514 "filename": "sample_2054", 2515 "file_path": "/uploads/-/system/issuable_metric_image/file/18/sample_2054.png", 2516 "url": "example.com/metric" 2517 } 2518] 2519``` 2520 2521## Delete metric image 2522 2523Available only for Incident issues. 2524 2525```plaintext 2526DELETE /projects/:id/issues/:issue_iid/metric_images/:image_id 2527``` 2528 2529| Attribute | Type | Required | Description | 2530|-------------|---------|----------|--------------------------------------| 2531| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | 2532| `issue_iid` | integer | yes | The internal ID of a project's issue | 2533| `image_id` | integer | yes | The ID of the image | 2534 2535```shell 2536curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" 2537``` 2538 2539Can return the following status codes: 2540 2541- `204 No Content`, if the image was deleted successfully. 2542- `400 Bad Request`, if the image could not be deleted. 2543
