2017-05-10 18:48:07 +00:00
# Issues API
2014-05-27 12:12:15 +00:00
2016-01-18 08:10:46 +00:00
Every API call to issues must be authenticated.
If a user is not a member of a project and the project is private, a `GET`
request on that project will result to a `404` status code.
## Issues pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
Read more on [pagination ](README.md#pagination ).
2012-07-24 12:25:01 +00:00
## List issues
2016-01-18 08:10:46 +00:00
Get all issues created by the authenticated user.
2012-07-24 12:25:01 +00:00
```
GET /issues
2014-08-14 10:41:16 +00:00
GET /issues?state=opened
GET /issues?state=closed
2014-08-14 14:17:19 +00:00
GET /issues?labels=foo
GET /issues?labels=foo,bar
GET /issues?labels=foo,bar& state=opened
2016-10-26 08:08:58 +00:00
GET /issues?milestone=1.0.0
GET /issues?milestone=1.0.0& state=opened
2017-02-23 13:29:35 +00:00
GET /issues?iids[]=42& iids[]=43
2017-03-31 01:11:12 +00:00
GET /issues?search=issue+title+or+description
2012-07-24 12:25:01 +00:00
```
2017-03-31 01:11:12 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------|
2017-03-31 01:11:12 +00:00
| `state` | string | no | Return all issues or just those that are `opened` or `closed` |
| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
| `milestone` | string | no | The milestone title |
| `iids` | Array[integer] | no | Return only the issues having the given `iid` |
| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
2017-04-06 15:18:51 +00:00
| `search` | string | no | Search issues against their `title` and `description` |
2016-01-18 08:10:46 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues
2016-01-18 08:10:46 +00:00
```
2014-08-14 10:41:16 +00:00
2016-01-18 08:10:46 +00:00
Example response:
2014-08-14 10:41:16 +00:00
2012-07-24 12:25:01 +00:00
```json
[
2016-01-18 08:10:46 +00:00
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/eileen.lowe",
2016-01-18 08:10:46 +00:00
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"username" : "eileen.lowe"
},
"milestone" : {
"project_id" : 1,
"description" : "Ducimus nam enim ex consequatur cumque ratione.",
"state" : "closed",
"due_date" : null,
"iid" : 2,
"created_at" : "2016-01-04T15:31:39.996Z",
"title" : "v4.0",
"id" : 17,
"updated_at" : "2016-01-04T15:31:39.996Z"
},
"project_id" : 1,
2017-05-04 12:11:15 +00:00
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
2016-01-18 08:10:46 +00:00
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/root",
2016-01-18 08:10:46 +00:00
"avatar_url" : null,
"username" : "root"
},
"updated_at" : "2016-01-04T15:31:51.081Z",
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"iid" : 6,
2016-04-08 06:41:10 +00:00
"labels" : [],
2016-07-12 15:59:21 +00:00
"user_notes_count": 1,
2016-08-02 17:37:04 +00:00
"due_date": "2016-07-22",
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/6",
"confidential": false
2016-04-08 06:41:10 +00:00
}
2012-07-24 12:25:01 +00:00
]
```
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2016-06-07 22:01:54 +00:00
## List group issues
Get a list of a group's issues.
```
GET /groups/:id/issues
GET /groups/:id/issues?state=opened
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?labels=foo
GET /groups/:id/issues?labels=foo,bar
GET /groups/:id/issues?labels=foo,bar& state=opened
GET /groups/:id/issues?milestone=1.0.0
GET /groups/:id/issues?milestone=1.0.0& state=opened
2017-02-23 13:29:35 +00:00
GET /groups/:id/issues?iids[]=42& iids[]=43
2017-03-31 01:11:12 +00:00
GET /groups/:id/issues?search=issue+title+or+description
2016-06-07 22:01:54 +00:00
```
2017-03-31 01:11:12 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the group ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-31 01:11:12 +00:00
| `state` | string | no | Return all issues or just those that are `opened` or `closed` |
| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
| `iids` | Array[integer] | no | Return only the issues having the given `iid` |
| `milestone` | string | no | The milestone title |
| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
| `search` | string | no | Search group issues against their `title` and `description` |
2016-06-07 22:01:54 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/4/issues
2016-06-07 22:01:54 +00:00
```
Example response:
```json
[
{
"project_id" : 4,
"milestone" : {
"due_date" : null,
"project_id" : 4,
"state" : "closed",
"description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
"iid" : 3,
"id" : 11,
"title" : "v3.0",
"created_at" : "2016-01-04T15:31:39.788Z",
"updated_at" : "2016-01-04T15:31:39.788Z"
},
"author" : {
"state" : "active",
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/root",
2016-06-07 22:01:54 +00:00
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
2017-05-04 12:11:15 +00:00
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
2016-06-07 22:01:54 +00:00
"assignee" : {
"avatar_url" : null,
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/lennie",
2016-06-07 22:01:54 +00:00
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"labels" : [],
"id" : 41,
"title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
"updated_at" : "2016-01-04T15:31:46.176Z",
"created_at" : "2016-01-04T15:31:46.176Z",
2016-07-12 15:59:21 +00:00
"user_notes_count": 1,
2016-08-02 17:37:04 +00:00
"due_date": null,
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/1",
"confidential": false
2016-06-07 22:01:54 +00:00
}
]
```
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2012-07-24 12:25:01 +00:00
## List project issues
2016-01-18 08:10:46 +00:00
Get a list of a project's issues.
2012-07-24 12:25:01 +00:00
```
GET /projects/:id/issues
2014-08-14 10:41:16 +00:00
GET /projects/:id/issues?state=opened
GET /projects/:id/issues?state=closed
2014-08-14 14:17:19 +00:00
GET /projects/:id/issues?labels=foo
GET /projects/:id/issues?labels=foo,bar
GET /projects/:id/issues?labels=foo,bar& state=opened
2014-09-04 22:01:12 +00:00
GET /projects/:id/issues?milestone=1.0.0
GET /projects/:id/issues?milestone=1.0.0& state=opened
2017-02-23 13:29:35 +00:00
GET /projects/:id/issues?iids[]=42& iids[]=43
2017-03-31 01:11:12 +00:00
GET /projects/:id/issues?search=issue+title+or+description
2012-07-24 12:25:01 +00:00
```
2017-03-31 01:11:12 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-31 01:11:12 +00:00
| `iids` | Array[integer] | no | Return only the milestone having the given `iid` |
| `state` | string | no | Return all issues or just those that are `opened` or `closed` |
| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels |
| `milestone` | string | no | The milestone title |
| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
| `search` | string | no | Search project issues against their `title` and `description` |
2016-01-18 08:10:46 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues
2016-01-18 08:10:46 +00:00
```
Example response:
2012-07-24 12:25:01 +00:00
2016-01-18 08:10:46 +00:00
```json
[
{
"project_id" : 4,
"milestone" : {
"due_date" : null,
"project_id" : 4,
"state" : "closed",
"description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
"iid" : 3,
"id" : 11,
"title" : "v3.0",
"created_at" : "2016-01-04T15:31:39.788Z",
"updated_at" : "2016-01-04T15:31:39.788Z"
},
"author" : {
"state" : "active",
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/root",
2016-01-18 08:10:46 +00:00
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
2017-05-04 12:11:15 +00:00
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
2016-01-18 08:10:46 +00:00
"assignee" : {
"avatar_url" : null,
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/lennie",
2016-01-18 08:10:46 +00:00
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"labels" : [],
"id" : 41,
"title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
"updated_at" : "2016-01-04T15:31:46.176Z",
2016-04-08 06:41:10 +00:00
"created_at" : "2016-01-04T15:31:46.176Z",
2016-07-12 15:59:21 +00:00
"user_notes_count": 1,
2016-08-02 17:37:04 +00:00
"due_date": "2016-07-22",
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/1",
"confidential": false
2016-01-18 08:10:46 +00:00
}
]
```
2013-02-27 13:36:20 +00:00
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2012-07-24 12:25:01 +00:00
## Single issue
2016-01-18 08:10:46 +00:00
Get a single project issue.
2012-07-24 12:25:01 +00:00
```
2017-03-01 06:57:34 +00:00
GET /projects/:id/issues/:issue_iid
2012-07-24 12:25:01 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
2012-07-24 12:25:01 +00:00
2016-01-18 08:10:46 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/41
2016-01-18 08:10:46 +00:00
```
Example response:
2012-07-24 12:25:01 +00:00
```json
{
2016-01-18 08:10:46 +00:00
"project_id" : 4,
"milestone" : {
"due_date" : null,
"project_id" : 4,
"state" : "closed",
"description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
"iid" : 3,
"id" : 11,
"title" : "v3.0",
"created_at" : "2016-01-04T15:31:39.788Z",
"updated_at" : "2016-01-04T15:31:39.788Z"
},
"author" : {
"state" : "active",
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/root",
2016-01-18 08:10:46 +00:00
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
2017-05-04 12:11:15 +00:00
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
2016-01-18 08:10:46 +00:00
"assignee" : {
"avatar_url" : null,
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/lennie",
2016-01-18 08:10:46 +00:00
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"labels" : [],
"id" : 41,
"title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
"updated_at" : "2016-01-04T15:31:46.176Z",
2016-04-08 06:41:10 +00:00
"created_at" : "2016-01-04T15:31:46.176Z",
2016-02-23 21:59:32 +00:00
"subscribed": false,
2016-07-12 15:59:21 +00:00
"user_notes_count": 1,
2016-08-02 17:37:04 +00:00
"due_date": null,
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/1",
"confidential": false
2012-07-24 12:25:01 +00:00
}
```
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2012-07-24 12:25:01 +00:00
## New issue
2013-02-27 13:36:20 +00:00
Creates a new project issue.
2012-07-24 12:25:01 +00:00
```
POST /projects/:id/issues
```
2017-05-04 12:11:15 +00:00
| Attribute | Type | Required | Description |
|-------------------------------------------|----------------|----------|--------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-04-06 15:18:51 +00:00
| `title` | string | yes | The title of an issue |
| `description` | string | no | The description of an issue |
| `confidential` | boolean | no | Set an issue to be confidential. Default is `false` . |
2017-05-08 14:58:42 +00:00
| `assignee_ids` | Array[integer] | no | The ID of the users to assign issue |
2017-04-06 15:18:51 +00:00
| `milestone_id` | integer | no | The ID of a milestone to assign issue |
| `labels` | string | no | Comma-separated label names for an issue |
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` |
| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.|
| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of` . |
2016-01-18 08:10:46 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth& labels=bug
2016-01-18 08:10:46 +00:00
```
2012-07-24 12:25:01 +00:00
2016-01-18 08:10:46 +00:00
Example response:
2012-07-24 12:25:01 +00:00
2016-01-18 08:10:46 +00:00
```json
{
"project_id" : 4,
"id" : 84,
"created_at" : "2016-01-07T12:44:33.959Z",
"iid" : 14,
"title" : "Issues with auth",
"state" : "opened",
2017-05-04 12:11:15 +00:00
"assignees" : [],
2016-01-18 08:10:46 +00:00
"assignee" : null,
"labels" : [
"bug"
],
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"state" : "active",
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/eileen.lowe",
2016-01-18 08:10:46 +00:00
"id" : 18,
"username" : "eileen.lowe"
},
"description" : null,
"updated_at" : "2016-01-07T12:44:33.959Z",
2016-04-08 06:41:10 +00:00
"milestone" : null,
2016-02-23 21:59:32 +00:00
"subscribed" : true,
2016-07-12 15:59:21 +00:00
"user_notes_count": 0,
2016-08-02 17:37:04 +00:00
"due_date": null,
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/14",
"confidential": false
2016-01-18 08:10:46 +00:00
}
```
2014-08-14 08:17:52 +00:00
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2012-07-24 12:25:01 +00:00
## Edit issue
2016-01-18 08:10:46 +00:00
Updates an existing project issue. This call is also used to mark an issue as
closed.
2012-07-24 12:25:01 +00:00
```
2017-03-01 06:57:34 +00:00
PUT /projects/:id/issues/:issue_iid
2012-07-24 12:25:01 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|----------------|---------|----------|------------------------------------------------------------------------------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
| `title` | string | no | The title of an issue |
| `description` | string | no | The description of an issue |
| `confidential` | boolean | no | Updates an issue to be confidential |
2017-05-08 14:58:42 +00:00
| `assignee_ids` | Array[integer] | no | The ID of the users to assign the issue to |
2017-03-01 06:57:34 +00:00
| `milestone_id` | integer | no | The ID of a milestone to assign the issue to |
| `labels` | string | no | Comma-separated label names for an issue |
| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it |
| `updated_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` |
2016-01-18 08:10:46 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close
2016-01-18 08:10:46 +00:00
```
2012-07-24 12:25:01 +00:00
2016-01-18 08:10:46 +00:00
Example response:
2013-02-27 13:36:20 +00:00
2016-01-18 08:10:46 +00:00
```json
{
"created_at" : "2016-01-07T12:46:01.410Z",
"author" : {
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"username" : "eileen.lowe",
"id" : 18,
"state" : "active",
2016-10-13 11:24:09 +00:00
"web_url" : "https://gitlab.example.com/eileen.lowe"
2016-01-18 08:10:46 +00:00
},
"state" : "closed",
"title" : "Issues with auth",
"project_id" : 4,
"description" : null,
"updated_at" : "2016-01-07T12:55:16.213Z",
"iid" : 15,
"labels" : [
"bug"
],
"id" : 85,
2017-05-04 12:11:15 +00:00
"assignees" : [],
2016-01-18 08:10:46 +00:00
"assignee" : null,
2016-04-08 06:41:10 +00:00
"milestone" : null,
2016-02-23 21:59:32 +00:00
"subscribed" : true,
2016-07-12 15:59:21 +00:00
"user_notes_count": 0,
2016-08-02 17:37:04 +00:00
"due_date": "2016-07-22",
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/15",
"confidential": false
2016-01-18 08:10:46 +00:00
}
```
2014-08-14 08:17:52 +00:00
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2016-03-21 13:12:52 +00:00
## Delete an issue
2013-02-27 13:36:20 +00:00
2016-03-21 13:12:52 +00:00
Only for admins and project owners. Soft deletes the issue in question.
2013-02-27 13:36:20 +00:00
```
2017-03-01 06:57:34 +00:00
DELETE /projects/:id/issues/:issue_iid
2013-02-27 13:36:20 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
2016-02-26 08:55:43 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85
2016-02-26 08:55:43 +00:00
```
2016-04-07 12:07:17 +00:00
## Move an issue
2016-11-24 17:28:52 +00:00
Moves an issue to a different project. If the target project
2016-04-12 16:38:18 +00:00
equals the source project or the user has insufficient permissions to move an
issue, error `400` together with an explaining error message is returned.
2016-04-07 12:07:17 +00:00
2016-05-06 10:52:04 +00:00
If a given label and/or milestone with the same name also exists in the target
project, it will then be assigned to the issue that is being moved.
2016-04-07 12:07:17 +00:00
```
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/move
2016-04-07 12:07:17 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-----------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
| `to_project_id` | integer | yes | The ID of the new project |
2016-04-07 12:07:17 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85/move
2016-04-07 12:07:17 +00:00
```
Example response:
```json
{
"id": 92,
"iid": 11,
"project_id": 5,
"title": "Sit voluptas tempora quisquam aut doloribus et.",
"description": "Repellat voluptas quibusdam voluptatem exercitationem.",
"state": "opened",
"created_at": "2016-04-05T21:41:45.652Z",
"updated_at": "2016-04-07T12:20:17.596Z",
"labels": [],
"milestone": null,
2017-05-04 12:11:15 +00:00
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80& d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2016-04-07 12:07:17 +00:00
"assignee": {
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "https://gitlab.example.com/axel.block"
2016-04-07 12:07:17 +00:00
},
"author": {
"name": "Kris Steuber",
"username": "solon.cremin",
"id": 10,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "https://gitlab.example.com/solon.cremin"
2016-07-12 15:59:21 +00:00
},
2016-08-02 17:37:04 +00:00
"due_date": null,
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/11",
"confidential": false
2016-04-07 12:07:17 +00:00
}
```
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2016-04-08 12:17:42 +00:00
## Subscribe to an issue
2016-10-26 21:21:50 +00:00
Subscribes the authenticated user to an issue to receive notifications.
2016-11-24 17:28:52 +00:00
If the user is already subscribed to the issue, the status code `304`
is returned.
2016-04-08 12:17:42 +00:00
```
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/subscribe
2016-04-08 12:17:42 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
2016-04-08 12:17:42 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe
2016-04-08 12:17:42 +00:00
```
Example response:
```json
{
"id": 92,
"iid": 11,
"project_id": 5,
"title": "Sit voluptas tempora quisquam aut doloribus et.",
"description": "Repellat voluptas quibusdam voluptatem exercitationem.",
"state": "opened",
"created_at": "2016-04-05T21:41:45.652Z",
"updated_at": "2016-04-07T12:20:17.596Z",
"labels": [],
"milestone": null,
2017-05-04 12:11:15 +00:00
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80& d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2016-04-08 12:17:42 +00:00
"assignee": {
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "https://gitlab.example.com/axel.block"
2016-04-08 12:17:42 +00:00
},
"author": {
"name": "Kris Steuber",
"username": "solon.cremin",
"id": 10,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "https://gitlab.example.com/solon.cremin"
2016-07-12 15:59:21 +00:00
},
2016-08-02 17:37:04 +00:00
"due_date": null,
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/11",
"confidential": false
2016-04-08 12:17:42 +00:00
}
```
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2016-04-08 12:17:42 +00:00
## Unsubscribe from an issue
2016-04-12 12:46:59 +00:00
Unsubscribes the authenticated user from the issue to not receive notifications
2016-11-24 17:28:52 +00:00
from it. If the user is not subscribed to the issue, the
status code `304` is returned.
2016-04-08 12:17:42 +00:00
```
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/unsubscribe
2016-04-08 12:17:42 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
2016-04-08 12:17:42 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe
2016-04-08 12:17:42 +00:00
```
2016-06-28 16:04:44 +00:00
## Create a todo
2016-11-24 17:28:52 +00:00
Manually creates a todo for the current user on an issue. If
2016-06-28 16:04:44 +00:00
there already exists a todo for the user on that issue, status code `304` is
returned.
```
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/todo
2016-06-28 16:04:44 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
2016-06-28 16:04:44 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/todo
2016-06-28 16:04:44 +00:00
```
Example response:
```json
{
"id": 112,
"project": {
"id": 5,
"name": "Gitlab Ci",
"name_with_namespace": "Gitlab Org / Gitlab Ci",
"path": "gitlab-ci",
"path_with_namespace": "gitlab-org/gitlab-ci"
},
"author": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "https://gitlab.example.com/root"
2016-06-28 16:04:44 +00:00
},
"action_name": "marked",
"target_type": "Issue",
"target": {
"id": 93,
"iid": 10,
"project_id": 5,
"title": "Vel voluptas atque dicta mollitia adipisci qui at.",
"description": "Tempora laboriosam sint magni sed voluptas similique.",
"state": "closed",
"created_at": "2016-06-17T07:47:39.486Z",
"updated_at": "2016-07-01T11:09:13.998Z",
"labels": [],
"milestone": {
"id": 26,
"iid": 1,
"project_id": 5,
"title": "v0.0",
"description": "Accusantium nostrum rerum quae quia quis nesciunt suscipit id.",
"state": "closed",
"created_at": "2016-06-17T07:47:33.832Z",
"updated_at": "2016-06-17T07:47:33.832Z",
"due_date": null
},
2017-05-04 12:11:15 +00:00
"assignees": [{
"name": "Jarret O'Keefe",
"username": "francisca",
"id": 14,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80& d=identicon",
"web_url": "https://gitlab.example.com/francisca"
}],
2016-06-28 16:04:44 +00:00
"assignee": {
"name": "Jarret O'Keefe",
"username": "francisca",
"id": 14,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "https://gitlab.example.com/francisca"
2016-06-28 16:04:44 +00:00
},
"author": {
"name": "Maxie Medhurst",
"username": "craig_rutherford",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "https://gitlab.example.com/craig_rutherford"
2016-06-28 16:04:44 +00:00
},
"subscribed": true,
"user_notes_count": 7,
"upvotes": 0,
2016-08-02 17:37:04 +00:00
"downvotes": 0,
"due_date": null,
2016-07-15 14:21:53 +00:00
"web_url": "http://example.com/example/example/issues/110",
"confidential": false
2016-06-28 16:04:44 +00:00
},
"target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/issues/10",
"body": "Vel voluptas atque dicta mollitia adipisci qui at.",
"state": "pending",
"created_at": "2016-07-01T11:09:13.992Z"
}
```
2017-05-08 14:58:42 +00:00
**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2017-05-04 12:11:15 +00:00
2017-01-18 16:48:16 +00:00
## Set a time estimate for an issue
Sets an estimated time of work for this issue.
```
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/time_estimate
2017-01-18 16:48:16 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|------------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
| `duration` | string | yes | The duration in human format. e.g: 3h30m |
2017-01-18 16:48:16 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m
2017-01-18 16:48:16 +00:00
```
Example response:
```json
{
"human_time_estimate": "3h 30m",
"human_total_time_spent": null,
"time_estimate": 12600,
"total_time_spent": 0
}
```
## Reset the time estimate for an issue
Resets the estimated time for this issue to 0 seconds.
```
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/reset_time_estimate
2017-01-18 16:48:16 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
2017-01-18 16:48:16 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate
2017-01-18 16:48:16 +00:00
```
Example response:
```json
{
"human_time_estimate": null,
"human_total_time_spent": null,
"time_estimate": 0,
"total_time_spent": 0
}
```
## Add spent time for an issue
Adds spent time for this issue
```
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/add_spent_time
2017-01-18 16:48:16 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|------------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
| `duration` | string | yes | The duration in human format. e.g: 3h30m |
2017-01-18 16:48:16 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h
2017-01-18 16:48:16 +00:00
```
Example response:
```json
{
"human_time_estimate": null,
"human_total_time_spent": "1h",
"time_estimate": 0,
"total_time_spent": 3600
}
```
## Reset spent time for an issue
Resets the total spent time for this issue to 0 seconds.
```
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/reset_spent_time
2017-01-18 16:48:16 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
2017-01-18 16:48:16 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time
2017-01-18 16:48:16 +00:00
```
Example response:
```json
{
"human_time_estimate": null,
"human_total_time_spent": null,
"time_estimate": 0,
"total_time_spent": 0
}
```
## Get time tracking stats
```
2017-03-01 06:57:34 +00:00
GET /projects/:id/issues/:issue_iid/time_stats
2017-01-18 16:48:16 +00:00
```
2017-03-01 06:57:34 +00:00
| Attribute | Type | Required | Description |
2017-04-06 15:18:51 +00:00
|-------------|---------|----------|--------------------------------------|
2017-04-10 13:29:51 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-03-01 06:57:34 +00:00
| `issue_iid` | integer | yes | The internal ID of a project's issue |
2017-01-18 16:48:16 +00:00
```bash
2017-03-01 17:39:40 +00:00
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats
2017-01-18 16:48:16 +00:00
```
Example response:
```json
{
"human_time_estimate": "2h",
"human_total_time_spent": "1h",
"time_estimate": 7200,
"total_time_spent": 3600
}
```
2017-04-12 11:38:00 +00:00
## List merge requests that will close issue on merge
Get all the merge requests that will close issue when merged.
```
GET /projects/:id/issues/:issue_iid/closed_by
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `issue_iid` | integer | yes | The internal ID of a project issue |
```bash
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by
```
Example response:
```json
[
{
"id": 6471,
"iid": 6432,
"project_id": 1,
"title": "add a test for cgi lexer options",
"description": "closes #11 ",
"state": "opened",
"created_at": "2017-04-06T18:33:34.168Z",
"updated_at": "2017-04-09T20:10:24.983Z",
"target_branch": "master",
"source_branch": "feature.custom-highlighting",
"upvotes": 0,
"downvotes": 0,
"author": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "https://gitlab.example.com/root"
},
"assignee": null,
"source_project_id": 1,
"target_project_id": 1,
"labels": [],
"work_in_progress": false,
"milestone": null,
"merge_when_pipeline_succeeds": false,
"merge_status": "unchecked",
"sha": "5a62481d563af92b8e32d735f2fa63b94e806835",
"merge_commit_sha": null,
"user_notes_count": 1,
"should_remove_source_branch": null,
"force_remove_source_branch": false,
"web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/merge_requests/6432"
}
]
```
2014-04-30 15:28:05 +00:00
## Comments on issues
2016-01-18 08:10:46 +00:00
Comments are done via the [notes ](notes.md ) resource.