Issues API
DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Interact with GitLab Issues using the REST API.
If a user is not a member of a private project, a GET
request on that project results in 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.
NOTE:
The references.relative attribute is relative to the group or project of the issue being requested.
When an issue is fetched from its project, the relative format is the same as the short format.
When requested across groups or projects, it's expected to be the same as the full format.
List issues
Get all issues the authenticated user has access to. By default it
returns only issues created by the current user. To get all issues,
use parameter scope=all.
GET /issues
GET /issues?assignee_id=5
GET /issues?author_id=5
GET /issues?confidential=true
GET /issues?iids[]=42&iids[]=43
GET /issues?labels=foo
GET /issues?labels=foo,bar
GET /issues?labels=foo,bar&state=opened
GET /issues?milestone=1.0.0
GET /issues?milestone=1.0.0&state=opened
GET /issues?my_reaction_emoji=star
GET /issues?search=foo&in=title
GET /issues?state=closed
GET /issues?state=openedSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
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. |
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. |
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. |
author_username |
string | No | Return issues created by the given username. Similar to author_id and mutually exclusive with author_id. |
confidential |
boolean | No | Filter confidential or public issues. |
created_after |
datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z). |
created_before |
datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z). |
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), any, today, tomorrow, overdue, week, month, next_month_and_previous_two_weeks. |
epic_id |
integer | No | Return issues associated with the given epic ID. None returns issues that are not associated with an epic. Any returns issues that are associated with an epic. Premium and Ultimate only. |
health_status |
string | No | Return issues with the specified health_status. (Introduced in GitLab 15.4). In GitLab 15.5 and later, None returns issues with no health status assigned, and Any returns issues with a health status assigned. Ultimate only. |
iids[] |
integer array | No | Return only the issues having the given iid. |
in |
string | No | Modify the scope of the search attribute. title, description, or a string joining them with comma. Default is title,description. |
issue_type |
string | No | Filter to a given type of issue. One of issue, incident, test_case or task. |
iteration_id |
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. Premium and Ultimate only. |
iteration_title |
string | No | Return issues assigned to the iteration with the given title. Similar to iteration_id and mutually exclusive with iteration_id. Premium and Ultimate only. |
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. |
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. |
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. Use milestone_id attribute instead. milestone and milestone_id are mutually exclusive. |
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. |
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. |
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. |
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. |
scope |
string | No | Return issues for the given scope: created_by_me, assigned_to_me or all. Defaults to created_by_me. |
search |
string | No | Search issues against their title and description. |
sort |
string | No | Return issues sorted in asc or desc order. Default is desc. |
state |
string | No | Return all issues or just those that are opened or closed. |
updated_after |
datetime | No | Return issues updated on or after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z). |
updated_before |
datetime | No | Return issues updated on or before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z). |
weight |
integer | No | Return issues with the specified weight. None returns issues with no weight assigned. Any returns issues with a weight assigned. Premium and Ultimate only. |
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. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"Example response:
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]Issues created by users on GitLab Premium or Ultimate include the weight property:
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]Issues created by users on GitLab Premium or Ultimate include the epic property:
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}Issues created by users on GitLab Premium or Ultimate include the iteration property:
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}Issues created by users on GitLab Ultimate include the health_status property:
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]WARNING:
The assignee column is deprecated. We now show it as a single-sized array assignees to conform
to the GitLab EE API.
WARNING:
The epic_iid attribute is deprecated and scheduled for removal in API version 5.
Use iid of the epic attribute instead.
List group issues
Get a list of a group's issues.
If the group is private, you must provide credentials to authorize. The preferred way to do this, is by using personal access tokens.
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=openedSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer/string | Yes | The global ID or URL-encoded path of the group. |
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. |
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. |
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. |
author_username |
string | No | Return issues created by the given username. Similar to author_id and mutually exclusive with author_id. |
confidential |
boolean | No | Filter confidential or public issues. |
created_after |
datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z). |
created_before |
datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z). |
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), any, today, tomorrow, overdue, week, month, next_month_and_previous_two_weeks. |
epic_id |
integer | No | Return issues associated with the given epic ID. None returns issues that are not associated with an epic. Any returns issues that are associated with an epic. Premium and Ultimate only. |
iids[] |
integer array | No | Return only the issues having the given iid. |
issue_type |
string | No | Filter to a given type of issue. One of issue, incident, test_case or task. |
iteration_id |
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. Premium and Ultimate only. |
iteration_title |
string | No | Return issues assigned to the iteration with the given title. Similar to iteration_id and mutually exclusive with iteration_id. Premium and Ultimate only. |
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. |
milestone |
string | No | The milestone title. None lists all issues with no milestone. Any lists all issues that have an assigned milestone. |
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. |
non_archived |
boolean | No | Return issues from non archived projects. Default is true. |
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. |
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
|
scope |
string | No | Return issues for the given scope: created_by_me, assigned_to_me or all. Defaults to all. |
search |
string | No | Search group issues against their title and description. |
sort |
string | No | Return issues sorted in asc or desc order. Default is desc. |
state |
string | No | Return all issues or just those that are opened or closed. |
updated_after |
datetime | No | Return issues updated on or after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z). |
updated_before |
datetime | No | Return issues updated on or before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z). |
weight |
integer | No | Return issues with the specified weight. None returns issues with no weight assigned. Any returns issues with a weight assigned. Premium and Ultimate only. |
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. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"Example response:
[
{
"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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]Issues created by users on GitLab Premium or Ultimate include the weight property:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```0
Issues created by users on GitLab Premium or Ultimate include the `epic` property:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```1
Issues created by users on GitLab Ultimate include the `health_status` property:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```2
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
## List project issues
Get a list of a project's issues.
If the project is private, you need to provide credentials to authorize.
The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md).
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```3
Supported attributes:
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `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. |
| `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. |
| `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`. |
| `author_username` | string | No | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. |
| `confidential` | boolean | No | Filter confidential or public issues. |
| `created_after` | datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `created_before` | datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `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), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. |
| `epic_id` | integer | No | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. Premium and Ultimate only. |
| `iids[]` | integer array | No | Return only the issues having the given `iid`. |
| `issue_type` | string | No | Filter to a given type of issue. One of `issue`, `incident`, `test_case` or `task`. |
| `iteration_id` | 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`. Premium and Ultimate only. |
| `iteration_title` | string | No | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. Premium and Ultimate only. |
| `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. |
| `milestone` | string | No | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. |
| `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. |
| `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`. |
| `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`. |
| `scope` | string | No | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. |
| `search` | string | No | Search project issues against their `title` and `description`. |
| `sort` | string | No | Return issues sorted in `asc` or `desc` order. Default is `desc`. |
| `state` | string | No | Return all issues or just those that are `opened` or `closed`. |
| `updated_after` | datetime | No | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `updated_before` | datetime | No | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `weight` | integer | No | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. Premium and Ultimate only. |
| `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`. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```4
Example response:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```5
Issues created by users on GitLab Premium or Ultimate include the `weight` property:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```6
Issues created by users on GitLab Premium or Ultimate include the `epic` property:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```7
Issues created by users on GitLab Ultimate include the `health_status` property:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```8
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
## Single issue
Only for administrators.
Get a single issue.
The preferred way to do this is by using [personal access tokens](../user/profile/personal_access_tokens.md).
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```9
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer | Yes | The ID of the issue. |
Example request:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```0
Example response:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```1
Issues created by users on GitLab Premium or Ultimate include the `weight` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```2
Issues created by users on GitLab Premium or Ultimate include the `epic` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```3
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status`
property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```4
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform
to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated, and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
## Single project issue
Get a single project issue.
If the project is private or the issue is confidential, you need to provide credentials to authorize.
The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md).
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```5
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```6
Example response:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```7
Issues created by users on GitLab Premium or Ultimate include the `weight` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```8
Issues created by users on GitLab Premium or Ultimate include the `epic` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
"web_url" : "https://gitlab.example.com/eileen.lowe",
"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,
"assignees" : [{
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
}],
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root"
},
"type" : "ISSUE",
"updated_at" : "2016-01-04T15:31:51.081Z",
"closed_at" : null,
"closed_by" : null,
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"moved_to_id" : null,
"iid" : 6,
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"user_notes_count": 1,
"due_date": "2016-07-22",
"imported":false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/6",
"references": {
"short": "#6",
"relative": "my-group/my-project#6",
"full": "my-group/my-project#6"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/1/issues/76",
"notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/1/issues/76/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/1",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```9
Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status`
property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```0
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
## New issue
Creates a new project issue.
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```1
Supported attributes:
| Attribute | Type | Required | Description |
|-------------------------------------------|----------------|----------|--------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `assignee_id` | integer | No | The ID of the user to assign the issue to. Only appears on GitLab Free. |
| `assignee_ids` | integer array | No | The IDs of the users to assign the issue to. Premium and Ultimate only.|
| `confidential` | boolean | No | Set an issue to be confidential. Default is `false`. |
| `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. |
| `description` | string | No | The description of an issue. Limited to 1,048,576 characters. |
| `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`. |
| `due_date` | string | No | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11`. |
| `epic_id` | integer | No | ID of the epic to add the issue to. Valid values are greater than or equal to 0. Premium and Ultimate only. |
| `epic_iid` | 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). Premium and Ultimate only. |
| `iid` | integer/string | No | The internal ID of the project's issue (requires administrator or project owner rights). |
| `issue_type` | string | No | The type of issue. One of `issue`, `incident`, `test_case` or `task`. Default is `issue`. |
| `labels` | string | No | Comma-separated label names to assign to the new issue. If a label does not already exist, this creates a new project label and assigns it to the issue. |
| `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.|
| `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. |
| `title` | string | Yes | The title of an issue. |
| `weight` | integer | No | The weight of the issue. Valid values are greater than or equal to 0. Premium and Ultimate only. |
Example request:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```2
Example response:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```3
Issues created by users on GitLab Premium or Ultimate include the `weight` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```4
Issues created by users on GitLab Premium or Ultimate include the `epic` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```5
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```6
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
### Rate limits
To help avoid abuse, users can be limited to a specific number of `Create` requests per minute.
See [Issues rate limits](../administration/settings/rate_limit_on_issues_creation.md).
## Edit an issue
Updates an existing project issue. This request is also used to close or reopen an issue (with `state_event`).
At least one of the following parameters is required for the request to be successful:
- `:assignee_id`
- `:assignee_ids`
- `:confidential`
- `:created_at`
- `:description`
- `:discussion_locked`
- `:due_date`
- `:issue_type`
- `:labels`
- `:milestone_id`
- `:state_event`
- `:title`
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```7
Supported attributes:
| Attribute | Type | Required | Description |
|----------------|---------|----------|------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
| `add_labels` | string | No | Comma-separated label names to add to an issue. If a label does not already exist, this creates a new project label and assigns it to the issue. |
| `assignee_ids` | integer array | No | The ID of the users to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. |
| `confidential` | boolean | No | Updates an issue to be confidential. |
| `description` | string | No | The description of an issue. Limited to 1,048,576 characters. |
| `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. |
| `due_date` | string | No | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11`. |
| `epic_id` | integer | No | ID of the epic to add the issue to. Valid values are greater than or equal to 0. Premium and Ultimate only. |
| `epic_iid` | 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). Premium and Ultimate only. |
| `issue_type` | string | No | Updates the type of issue. One of `issue`, `incident`, `test_case` or `task`. |
| `labels` | string | No | Comma-separated label names for an issue. Set to an empty string to unassign all labels. If a label does not already exist, this creates a new project label and assigns it to the issue. |
| `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.|
| `remove_labels`| string | No | Comma-separated label names to remove from an issue. |
| `state_event` | string | No | The state event of an issue. To close the issue, use `close`, and to reopen it, use `reopen`. |
| `title` | string | No | The title of an issue. |
| `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.|
| `weight` | integer | No | The weight of the issue. Valid values are greater than or equal to 0. Premium and Ultimate only. |
Example request:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```8
Example response:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"weight": null,
...
}
]
```9
Issues created by users on GitLab Premium or Ultimate include the `weight` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```0
Issues created by users on GitLab Premium or Ultimate include the `epic` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```1
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```2
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
WARNING:
`assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
## Delete an issue
Only for administrators and project owners.
Deletes an issue.
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```3
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```4
If successful, returns [`204 No Content`](rest/troubleshooting.md#status-codes).
## Reorder an issue
Reorders an issue. You can see the results when [sorting issues manually](../user/project/issues/sorting_issue_lists.md#manual-sorting).
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```5
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of the project's issue. |
| `move_after_id` | integer | No | The global ID of a project's issue that should be placed after this issue. |
| `move_before_id` | integer | No | The global ID of a project's issue that should be placed before this issue. |
Example request:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```6
## Move an issue
Moves an issue to a different project. If the target project
is the source project or the user has insufficient permissions,
an error message with status code `400` is returned.
If a given label or milestone with the same name also exists in the target
project, it's then assigned to the issue being moved.
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```7
Supported attributes:
| Attribute | Type | Required | Description |
|-----------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
| `to_project_id` | integer | Yes | The ID of the new project. |
Example request:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```8
Example response:
```json
{
"project_id" : 4,
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
"epic": {
"id" : 42,
"iid" : 5,
"title": "My epic epic",
"url" : "/groups/h5bp/-/epics/5",
"group_id": 8
},
...
}
```9
Issues created by users on GitLab Premium or Ultimate include the `weight` property:
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```0
Issues created by users on GitLab Premium or Ultimate include the `epic` property:
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```1
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```2
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
## Clone an issue
Clone the issue to given project.
Copies as much data as possible as long as the target project contains equivalent
criteria, such as labels or milestones.
If you have insufficient permissions, an error message with status code `400` is returned.
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```3
Supported attributes:
| Attribute | Type | Required | Description |
| --------------- | -------------- | ---------------------- | --------------------------------- |
| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | Internal ID of a project's issue. |
| `to_project_id` | integer | Yes | ID of the new project. |
| `with_notes` | boolean | No | Clone the issue with [notes](notes.md). Default is `false`. |
Example request:
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```4
Example response:
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```5
## Notifications
The following requests are related to [email notifications](../user/profile/notifications.md) for issues.
### Subscribe to an issue
Subscribes the authenticated user to an issue to receive notifications.
If the user is already subscribed to the issue, the status code `304`
is returned.
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```6
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```7
Example response:
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```8
Issues created by users on GitLab Premium or Ultimate include the `weight` property:
```json
{
"iteration": {
"id":90,
"iid":4,
"sequence":2,
"group_id":162,
"title":null,
"description":null,
"state":2,
"created_at":"2022-03-14T05:21:11.929Z",
"updated_at":"2022-03-14T05:21:11.929Z",
"start_date":"2022-03-08",
"due_date":"2022-03-14",
"web_url":"https://gitlab.com/groups/my-group/-/iterations/90"
}
...
}
```9
Issues created by users on GitLab Premium or Ultimate include the `epic` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```0
Issues created by users on GitLab Ultimate include the `health_status` property:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```1
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
WARNING:
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
### Unsubscribe from an issue
Unsubscribes the authenticated user from the issue to not receive notifications
from it. If the user is not subscribed to the issue, the
status code `304` is returned.
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```2
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```3
Example response:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```4
## Create a to-do item
Manually creates a to-do item for the current user on an issue. If
there already exists a to-do item for the user on that issue, status code `304` is
returned.
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```5
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```6
Example response:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```7
WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
## Promote an issue to an epic
DETAILS:
**Tier:** Premium, Ultimate
**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
Promotes an issue to an epic by adding a comment with the `/promote`
[quick action](../user/project/quick_actions.md).
For more information about promoting issues to epics, see
[Promote an issue to an epic](../user/project/issues/managing_issues.md#promote-an-issue-to-an-epic).
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```8
Supported attributes:
| Attribute | Type | Required | Description |
| :---------- | :------------- | :------- | :---------- |
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
| `body` | String | Yes | The content of a note. Must contain `/promote` at the start of a new line. If the note only contains `/promote`, promotes the issue, but doesn't add a comment. Otherwise, the other lines form a comment.|
Example request:
```json
[
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"health_status": "on_track",
...
}
]
```9
Example response:
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```0
## Time tracking
The following requests are related to [time tracking](../user/project/time_tracking.md) on issues.
### Set a time estimate for an issue
Sets an estimated time of work for this issue.
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```1
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|------------------------------------------|
| `duration` | string | Yes | The duration in human-readable format. For example: `3h30m`. |
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```2
Example response:
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```3
### Reset the time estimate for an issue
Resets the estimated time for this issue to 0 seconds.
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```4
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```5
Example response:
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```6
### Add spent time for an issue
Adds spent time for this issue.
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```7
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|------------------------------------------|
| `duration` | string | Yes | The duration in human-readable format. For example: `3h30m` |
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
| `summary` | string | No | A summary of how the time was spent. |
Example request:
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```8
Example response:
```plaintext
GET /groups/:id/issues
GET /groups/:id/issues?assignee_id=5
GET /groups/:id/issues?author_id=5
GET /groups/:id/issues?confidential=true
GET /groups/:id/issues?iids[]=42&iids[]=43
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
GET /groups/:id/issues?my_reaction_emoji=star
GET /groups/:id/issues?search=issue+title+or+description
GET /groups/:id/issues?state=closed
GET /groups/:id/issues?state=opened
```9
### Reset spent time for an issue
Resets the total spent time for this issue to 0 seconds.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```0
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```1
Example response:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```2
### Get time tracking stats
Gets time tracking stats for an issue in human-readable format (for example, `1h30m`) and in number of seconds.
If the project is private or the issue is confidential, you must provide credentials to authorize.
The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md).
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```3
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```4
Example response:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```5
## Merge requests
The following requests are related to relationships between issues and merge requests.
### List merge requests related to issue
Gets all the merge requests that are related to the issue.
If the project is private or the issue is confidential, you need to provide credentials to authorize.
The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md).
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```6
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```7
Example response:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```8
### List merge requests that close a particular issue on merge
Gets all merge requests that close a particular issue when merged.
If the project is private or the issue is confidential, you need to provide credentials to authorize.
The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md).
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/4/issues"
```9
Supported attributes:
| Attribute | Type | Required | Description |
| ----------- | ---------------| -------- | ---------------------------------- |
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project issue. |
Example request:
```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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```0
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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```1
## List participants in an issue
Lists users that are participants in the issue.
If the project is private or the issue is confidential, you need to provide credentials to authorize.
The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md).
```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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```2
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```3
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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```4
## Comments on issues
Interact with comments using the [Notes API](notes.md).
## Get user agent details
Available only for administrators.
Gets the user agent string and IP of the user who created the issue.
Used for spam tracking.
```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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```5
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```6
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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```7
## List issue state events
To track which state was set, who did it, and when it happened, use
[Resource state events API](resource_state_events.md#issues).
## Incidents
The following requests are available only for [incidents](../operations/incident_management/incidents.md).
### Upload metric image
Available only for [incidents](../operations/incident_management/incidents.md).
Uploads a screenshot of metric charts to show in the incident's **Metrics** tab.
When you upload an image, you can associate the image with text or a link to the original graph.
If you add a URL, you can access the original graph by selecting the hyperlink above the uploaded image.
```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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```8
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
| `file` | file | Yes | The image file to be uploaded. |
| `url` | string | No | The URL to view more metric information. |
| `url_text` | string | No | A description of the image or URL. |
Example request:
```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",
"web_url" : "https://gitlab.example.com/root",
"avatar_url" : null,
"username" : "root",
"id" : 1,
"name" : "Administrator"
},
"description" : "Omnis vero earum sunt corporis dolor et placeat.",
"state" : "closed",
"iid" : 1,
"assignees" : [{
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
}],
"assignee" : {
"avatar_url" : null,
"web_url" : "https://gitlab.example.com/lennie",
"state" : "active",
"username" : "lennie",
"id" : 9,
"name" : "Dr. Luella Kovacek"
},
"type" : "ISSUE",
"labels" : ["foo", "bar"],
"upvotes": 4,
"downvotes": 0,
"merge_requests_count": 0,
"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",
"closed_at" : null,
"closed_by" : null,
"user_notes_count": 1,
"due_date": null,
"imported": false,
"imported_from": "none",
"web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
"references": {
"short": "#1",
"relative": "my-project#1",
"full": "my-group/my-project#1"
},
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"has_tasks": true,
"task_status": "10 of 15 tasks completed",
"confidential": false,
"discussion_locked": false,
"issue_type": "issue",
"severity": "UNKNOWN",
"_links":{
"self":"http://gitlab.example.com/api/v4/projects/4/issues/41",
"notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes",
"award_emoji":"http://gitlab.example.com/api/v4/projects/4/issues/41/award_emoji",
"project":"http://gitlab.example.com/api/v4/projects/4",
"closed_as_duplicate_of": "http://gitlab.example.com/api/v4/projects/1/issues/75"
},
"task_completion_status":{
"count":0,
"completed_count":0
}
}
]
```9
Example response:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```00
### List metric images
Available only for [incidents](../operations/incident_management/incidents.md).
Lists screenshots of metric charts shown in the incident's **Metrics** tab.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```01
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```02
Example response:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```03
### Update metric image
Available only for [incidents](../operations/incident_management/incidents.md).
Edits attributes of a screenshot of metric charts shown in the incident's **Metrics** tab.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```04
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
| `image_id` | integer | Yes | The ID of the image. |
| `url` | string | No | The URL to view more metric information. |
| `url_text` | string | No | A description of the image or URL. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```05
Example response:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```06
### Delete metric image
Available only for [incidents](../operations/incident_management/incidents.md).
Delete a screenshot of metric charts shown in the incident's **Metrics** tab.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```07
Supported attributes:
| Attribute | Type | Required | Description |
|-------------|---------|----------|--------------------------------------|
| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `issue_iid` | integer | Yes | The internal ID of a project's issue. |
| `image_id` | integer | Yes | The ID of the image. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/issues"
```08
Can return the following status codes:
- `204 No Content`, if the image was deleted successfully.
- `400 Bad Request`, if the image could not be deleted.