Issues API

If a user is not a member of a project and the project is private, 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.

DANGER: Deprecated: The reference attribute in responses is deprecated in favor of references. Introduced in GitLab 12.6.

NOTE: 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, and 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=opened

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. (Introduced in GitLab 9.5)
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. (Introduced in GitLab 9.5)
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 (0) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: 0 (no due date), overdue, week, month, next_month_and_previous_two_weeks. (Introduced in GitLab 13.3)
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
iteration_id (STARTER)	integer	no	Return issues assigned to the given iteration ID. None returns issues that do not belong to an iteration. Any returns issues that belong to an iteration. Mutually exclusive with iteration_title. (Introduced in GitLab Starter 13.6)
iteration_title (STARTER)	string	no	Return issues assigned to the iteration with the given title. Similar to iteration_id and mutually exclusive with iteration_id. (Introduced in GitLab Starter 13.6)
milestone	string	no	The milestone title. None lists all issues with no milestone. Any lists all issues that have an assigned milestone.
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. (Introduced in GitLab 10.0)
non_archived	boolean	no	Return issues only from non-archived projects. If false, the response returns issues from both archived and non-archived projects. Default is true. (Introduced in GitLab 13.0)
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
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 created_by_me For versions before 11.0, use the now deprecated created-by-me or assigned-to-me scopes instead. (Introduced in GitLab 9.5. Changed to snake_case in GitLab 11.0)
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 (STARTER)	integer	no	Return issues with the specified weight. None returns issues with no weight assigned. Any returns issues with a weight assigned.
with_labels_details	boolean	no	If true, the response returns more details for each label in labels field: :name, :color, :description, :description_html, :text_color. Default is false. The description_html attribute was introduced in GitLab 12.7

curl --header "PRIVATE-TOKEN: <your_access_token>" "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"
      },
      "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",
      "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,
      "_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"
      },
      "task_completion_status":{
         "count":0,
         "completed_count":0
      }
   }
]

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

[
   {
      "state" : "opened",
      "description" : "Ratione dolores corrupti mollitia soluta quia.",
      "weight": null,
      ...
   }
]

Users on GitLab Ultimate can also see the health_status parameter:

[
   {
      "state" : "opened",
      "description" : "Ratione dolores corrupti mollitia soluta quia.",
      "health_status": "on_track",
      ...
   }
]

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

List group issues

Get a list of a group's issues.

If the group is private, credentials need to be provided for authorization. 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=opened

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. (Introduced in GitLab 9.5)
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. (Introduced in GitLab 9.5)
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 (0) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: 0 (no due date), overdue, week, month, next_month_and_previous_two_weeks. (Introduced in GitLab 13.3)
id	integer/string	yes	The ID or URL-encoded path of the group owned by the authenticated user
iids[]	integer array	no	Return only the issues having the given iid
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. (Introduced in GitLab 10.0)
non_archived	boolean	no	Return issues from non archived projects. Default is true. (Introduced in GitLab 12.8)
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. For versions before 11.0, use the now deprecated created-by-me or assigned-to-me scopes instead. (Introduced in GitLab 9.5. Changed to snake_case in GitLab 11.0)
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 (STARTER)	integer	no	Return issues with the specified weight. None returns issues with no weight assigned. Any returns issues with a weight assigned.
with_labels_details	boolean	no	If true, the response returns more details for each label in labels field: :name, :color, :description, :description_html, :text_color. Default is false. The description_html attribute was introduced in GitLab 12.7

curl --header "PRIVATE-TOKEN: <your_access_token>" "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"
      },
      "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,
      "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,
      "_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"
      },
      "task_completion_status":{
         "count":0,
         "completed_count":0
      }
   }
]

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

[
   {
      "project_id" : 4,
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "weight": null,
      ...
   }
]

Users on GitLab Ultimate can also see the health_status parameter:

[
   {
      "project_id" : 4,
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "health_status": "at_risk",
      ...
   }
]

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

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.

GET /projects/:id/issues
GET /projects/:id/issues?assignee_id=5
GET /projects/:id/issues?author_id=5
GET /projects/:id/issues?confidential=true
GET /projects/:id/issues?iids[]=42&iids[]=43
GET /projects/:id/issues?labels=foo
GET /projects/:id/issues?labels=foo,bar
GET /projects/:id/issues?labels=foo,bar&state=opened
GET /projects/:id/issues?milestone=1.0.0
GET /projects/:id/issues?milestone=1.0.0&state=opened
GET /projects/:id/issues?my_reaction_emoji=star
GET /projects/:id/issues?search=issue+title+or+description
GET /projects/:id/issues?state=closed
GET /projects/:id/issues?state=opened

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. (Introduced in GitLab 9.5)
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. (Introduced in GitLab 9.5)
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 (0) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: 0 (no due date), overdue, week, month, next_month_and_previous_two_weeks. (Introduced in GitLab 13.3)
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
iids[]	integer array	no	Return only the issues having the given iid
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. (Introduced in GitLab 10.0)
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. For versions before 11.0, use the now deprecated created-by-me or assigned-to-me scopes instead. (Introduced in GitLab 9.5. Changed to snake_case in GitLab 11.0)
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 (STARTER)	integer	no	Return issues with the specified weight. None returns issues with no weight assigned. Any returns issues with a weight assigned.
with_labels_details	boolean	no	If true, the response returns more details for each label in labels field: :name, :color, :description, :description_html, :text_color. Default is false. description_html was introduced in GitLab 12.7

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/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"
      },
      "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" : "2016-01-05T15:31:46.176Z",
      "closed_by" : {
         "state" : "active",
         "web_url" : "https://gitlab.example.com/root",
         "avatar_url" : null,
         "username" : "root",
         "id" : 1,
         "name" : "Administrator"
      },
      "user_notes_count": 1,
      "due_date": "2016-07-22",
      "web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
      "references": {
        "short": "#1",
        "relative": "#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,
      "_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"
      },
      "task_completion_status":{
         "count":0,
         "completed_count":0
      }
   }
]

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

[
   {
      "project_id" : 4,
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "weight": null,
      ...
   }
]

Users on GitLab Ultimate can also see the health_status parameter:

[
   {
      "project_id" : 4,
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "health_status": "at_risk",
      ...
   }
]

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

Single issue

Only for administrators. Get a single issue.

The preferred way to do this is by using personal access tokens.

GET /issues/:id

Attribute	Type	Required	Description
id	integer	yes	The ID of the issue

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues/41"

Example response:

{
   "id" : 1,
   "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",
      "closed_at" : "2016-01-05T15:31:46.176Z"
   },
   "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"
   },
   "labels" : [],
   "upvotes": 4,
   "downvotes": 0,
   "merge_requests_count": 0,
   "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,
   "subscribed": false,
   "user_notes_count": 1,
   "due_date": null,
   "web_url": "http://example.com/my-group/my-project/issues/1",
   "references": {
     "short": "#1",
     "relative": "#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
   },
   "confidential": false,
   "discussion_locked": false,
   "_links": {
      "self": "http://example.com/api/v4/projects/1/issues/2",
      "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
      "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji",
      "project": "http://example.com/api/v4/projects/1"
   },
   "task_completion_status":{
      "count":0,
      "completed_count":0
   },
   "weight": null,
  "has_tasks": false,
  "_links": {
    "self": "http://gitlab.example:3000/api/v4/projects/1/issues/1",
    "notes": "http://gitlab.example:3000/api/v4/projects/1/issues/1/notes",
    "award_emoji": "http://gitlab.example:3000/api/v4/projects/1/issues/1/award_emoji",
    "project": "http://gitlab.example:3000/api/v4/projects/1"
  },
  "references": {
    "short": "#1",
    "relative": "#1",
    "full": "gitlab-org/gitlab-test#1"
  },
  "subscribed": true,
  "moved_to_id": null,
  "epic_iid": null,
  "epic": null
}

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

{
   "project_id" : 4,
   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
   "weight": null,
   ...
}

Users on GitLab Ultimate can also see the epic property:

{
   "project_id" : 4,
   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
   "epic": {
   "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
   },
   // ...
}

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

DANGER: Deprecated: The epic_iid attribute is deprecated, and will be removed in version 5. Please use iid of the epic attribute instead.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

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.

GET /projects/:id/issues/:issue_iid

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/41"

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",
      "closed_at" : "2016-01-05T15:31:46.176Z"
   },
   "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"
   },
   "labels" : [],
   "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,
   "subscribed": false,
   "user_notes_count": 1,
   "due_date": null,
   "web_url": "http://gitlab.example.com/my-group/my-project/issues/1",
   "references": {
     "short": "#1",
     "relative": "#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
   },
   "confidential": false,
   "discussion_locked": false,
   "_links": {
      "self": "http://gitlab.example.com/api/v4/projects/1/issues/2",
      "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes",
      "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji",
      "project": "http://gitlab.example.com/api/v4/projects/1"
   },
   "task_completion_status":{
      "count":0,
      "completed_count":0
   }
}

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

{
   "project_id" : 4,
   "description" : "Omnis vero earum sunt corporis dolor et placeat.",
   "weight": null,
   ...
}

Users on GitLab Premium can also see 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
   },
   // ...
}

Users on GitLab Ultimate can also see the health_status property:

[
   {
      "project_id" : 4,
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "health_status": "on_track",
      ...
   }
]

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

DANGER: Deprecated: The epic_iid attribute is deprecated and will be removed in version 5. Please use iid of the epic attribute instead.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

New issue

Creates a new project issue.

POST /projects/:id/issues

Attribute	Type	Required	Description
assignee_ids	integer array	no	The ID of the user(s) to assign the issue to.
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 YEAR-MONTH-DAY, for example 2016-03-11
epic_id (PREMIUM)	integer	no	ID of the epic to add the issue to. Valid values are greater than or equal to 0.
epic_iid (PREMIUM)	integer	no	IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, will be removed in version 5)
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
iid	integer/string	no	The internal ID of the project's issue (requires administrator or project owner rights)
labels	string	no	Comma-separated label names for an 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
title	string	yes	The title of an issue
weight (STARTER)	integer	no	The weight of the issue. Valid values are greater than or equal to 0.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug"

Example response:

{
   "project_id" : 4,
   "id" : 84,
   "created_at" : "2016-01-07T12:44:33.959Z",
   "iid" : 14,
   "title" : "Issues with auth",
   "state" : "opened",
   "assignees" : [],
   "assignee" : null,
   "labels" : [
      "bug"
   ],
   "upvotes": 4,
   "downvotes": 0,
   "merge_requests_count": 0,
   "author" : {
      "name" : "Alexandra Bashirian",
      "avatar_url" : null,
      "state" : "active",
      "web_url" : "https://gitlab.example.com/eileen.lowe",
      "id" : 18,
      "username" : "eileen.lowe"
   },
   "description" : null,
   "updated_at" : "2016-01-07T12:44:33.959Z",
   "closed_at" : null,
   "closed_by" : null,
   "milestone" : null,
   "subscribed" : true,
   "user_notes_count": 0,
   "due_date": null,
   "web_url": "http://gitlab.example.com/my-group/my-project/issues/14",
   "references": {
     "short": "#14",
     "relative": "#14",
     "full": "my-group/my-project#14"
   },
   "time_stats": {
      "time_estimate": 0,
      "total_time_spent": 0,
      "human_time_estimate": null,
      "human_total_time_spent": null
   },
   "confidential": false,
   "discussion_locked": false,
   "_links": {
      "self": "http://gitlab.example.com/api/v4/projects/1/issues/2",
      "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes",
      "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji",
      "project": "http://gitlab.example.com/api/v4/projects/1"
   },
   "task_completion_status":{
      "count":0,
      "completed_count":0
   }
}

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

{
   "project_id" : 4,
   "description" : null,
   "weight": null,
   ...
}

Users on GitLab Ultimate can also see the health_status parameter:

[
   {
      "project_id" : 4,
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "health_status": "on_track",
      ...
   }
]

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

Rate limits

To help avoid abuse, users can be limited to a specific number of Create requests per minute. See Issues rate limits.

Edit issue

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

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
• :labels
• :milestone_id
• :state_event
• :title

PUT /projects/:id/issues/:issue_iid

Attribute	Type	Required	Description
add_labels	string	no	Comma-separated label names to add to an issue.
assignee_ids	integer array	no	The ID of the user(s) to assign the issue to. Set to 0 or provide an empty value to unassign all assignees.
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 YEAR-MONTH-DAY, for example 2016-03-11
epic_id (PREMIUM)	integer	no	ID of the epic to add the issue to. Valid values are greater than or equal to 0.
epic_iid (PREMIUM)	integer	no	IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, will be removed in version 5)
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue
labels	string	no	Comma-separated label names for an issue. Set to an empty string to unassign all labels.
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. Set close to close the issue and reopen to reopen it
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 (STARTER)	integer	no	The weight of the issue. Valid values are greater than or equal to 0. 0

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close"

Example response:

{
   "created_at" : "2016-01-07T12:46:01.410Z",
   "author" : {
      "name" : "Alexandra Bashirian",
      "avatar_url" : null,
      "username" : "eileen.lowe",
      "id" : 18,
      "state" : "active",
      "web_url" : "https://gitlab.example.com/eileen.lowe"
   },
   "state" : "closed",
   "title" : "Issues with auth",
   "project_id" : 4,
   "description" : null,
   "updated_at" : "2016-01-07T12:55:16.213Z",
   "closed_at" : "2016-01-08T12:55:16.213Z",
   "closed_by" : {
      "state" : "active",
      "web_url" : "https://gitlab.example.com/root",
      "avatar_url" : null,
      "username" : "root",
      "id" : 1,
      "name" : "Administrator"
    },
   "iid" : 15,
   "labels" : [
      "bug"
   ],
   "upvotes": 4,
   "downvotes": 0,
   "merge_requests_count": 0,
   "id" : 85,
   "assignees" : [],
   "assignee" : null,
   "milestone" : null,
   "subscribed" : true,
   "user_notes_count": 0,
   "due_date": "2016-07-22",
   "web_url": "http://gitlab.example.com/my-group/my-project/issues/15",
   "references": {
     "short": "#15",
     "relative": "#15",
     "full": "my-group/my-project#15"
   },
   "time_stats": {
      "time_estimate": 0,
      "total_time_spent": 0,
      "human_time_estimate": null,
      "human_total_time_spent": null
   },
   "confidential": false,
   "discussion_locked": false,
   "_links": {
      "self": "http://gitlab.example.com/api/v4/projects/1/issues/2",
      "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes",
      "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji",
      "project": "http://gitlab.example.com/api/v4/projects/1"
   },
   "task_completion_status":{
      "count":0,
      "completed_count":0
   }
}

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

{
   "project_id" : 4,
   "description" : null,
   "weight": null,
   ...
}

Users on GitLab Ultimate can also see the health_status parameter:

[
   {
      "project_id" : 4,
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "health_status": "on_track",
      ...
   }
]

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

DANGER: Deprecated: 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 admins and project owners. Deletes the issue in question.

DELETE /projects/:id/issues/:issue_iid

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85"

Reorder an issue

Introduced in GitLab 13.2.

Reorders an issue, you can see the results when sorting issues manually

PUT /projects/:id/issues/:issue_iid/reorder

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of the project's issue
move_after_id	integer	no	The ID of a project's issue that should be placed after this issue
move_before_id	integer	no	The ID of a project's issue that should be placed before this issue

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85/reorder?move_after_id=51&move_before_id=92"

Move an issue

Moves an issue to a different project. If the target project equals the source project or the user has insufficient permissions to move an issue, status code 400 and an error message 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.

POST /projects/:id/issues/:issue_iid/move

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue
to_project_id	integer	yes	The ID of the new project

curl --header "PRIVATE-TOKEN: <your_access_token>" --form to_project_id=5 "https://gitlab.example.com/api/v4/projects/4/issues/85/move"

Example response:

{
  "id": 92,
  "iid": 11,
  "project_id": 5,
  "title": "Sit voluptas tempora quisquam aut doloribus et.",
  "description": "Repellat voluptas quibusdam voluptatem exercitationem.",
  "state": "opened",
  "created_at": "2016-04-05T21:41:45.652Z",
  "updated_at": "2016-04-07T12:20:17.596Z",
  "closed_at": null,
  "closed_by": null,
  "labels": [],
  "upvotes": 4,
  "downvotes": 0,
  "merge_requests_count": 0,
  "milestone": null,
  "assignees": [{
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/axel.block"
  }],
  "assignee": {
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/axel.block"
  },
  "author": {
    "name": "Kris Steuber",
    "username": "solon.cremin",
    "id": 10,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/solon.cremin"
  },
  "due_date": null,
  "web_url": "http://gitlab.example.com/my-group/my-project/issues/11",
  "references": {
    "short": "#11",
    "relative": "#11",
    "full": "my-group/my-project#11"
  },
  "time_stats": {
    "time_estimate": 0,
    "total_time_spent": 0,
    "human_time_estimate": null,
    "human_total_time_spent": null
  },
  "confidential": false,
  "discussion_locked": false,
  "_links": {
    "self": "http://gitlab.example.com/api/v4/projects/1/issues/2",
    "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes",
    "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji",
    "project": "http://gitlab.example.com/api/v4/projects/1"
  },
  "task_completion_status":{
     "count":0,
     "completed_count":0
  }
}

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

{
  "project_id": 5,
  "description": "Repellat voluptas quibusdam voluptatem exercitationem.",
  "weight": null,
  ...
}

Users on GitLab Ultimate can also see the health_status parameter:

[
   {
      "project_id" : 4,
      "description" : "Omnis vero earum sunt corporis dolor et placeat.",
      "health_status": "on_track",
      ...
   }
]

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

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.

POST /projects/:id/issues/:issue_iid/subscribe

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe"

Example response:

{
  "id": 92,
  "iid": 11,
  "project_id": 5,
  "title": "Sit voluptas tempora quisquam aut doloribus et.",
  "description": "Repellat voluptas quibusdam voluptatem exercitationem.",
  "state": "opened",
  "created_at": "2016-04-05T21:41:45.652Z",
  "updated_at": "2016-04-07T12:20:17.596Z",
  "closed_at": null,
  "closed_by": null,
  "labels": [],
  "upvotes": 4,
  "downvotes": 0,
  "merge_requests_count": 0,
  "milestone": null,
  "assignees": [{
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/axel.block"
  }],
  "assignee": {
    "name": "Miss Monserrate Beier",
    "username": "axel.block",
    "id": 12,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/axel.block"
  },
  "author": {
    "name": "Kris Steuber",
    "username": "solon.cremin",
    "id": 10,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/7a190fecbaa68212a4b68aeb6e3acd10?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/solon.cremin"
  },
  "due_date": null,
  "web_url": "http://gitlab.example.com/my-group/my-project/issues/11",
  "references": {
    "short": "#11",
    "relative": "#11",
    "full": "my-group/my-project#11"
  },
  "time_stats": {
    "time_estimate": 0,
    "total_time_spent": 0,
    "human_time_estimate": null,
    "human_total_time_spent": null
  },
  "confidential": false,
  "discussion_locked": false,
  "_links": {
    "self": "http://gitlab.example.com/api/v4/projects/1/issues/2",
    "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes",
    "award_emoji": "http://gitlab.example.com/api/v4/projects/1/issues/2/award_emoji",
    "project": "http://gitlab.example.com/api/v4/projects/1"
  },
  "task_completion_status":{
     "count":0,
     "completed_count":0
  }
}

Users on GitLab Starter, Bronze, or higher can also see the weight parameter:

{
  "project_id": 5,
  "description": "Repellat voluptas quibusdam voluptatem exercitationem.",
  "weight": null,
  ...
}

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

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.

POST /projects/:id/issues/:issue_iid/unsubscribe

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe"

Example response:

{
  "id": 93,
  "iid": 12,
  "project_id": 5,
  "title": "Incidunt et rerum ea expedita iure quibusdam.",
  "description": "Et cumque architecto sed aut ipsam.",
  "state": "opened",
  "created_at": "2016-04-05T21:41:45.217Z",
  "updated_at": "2016-04-07T13:02:37.905Z",
  "labels": [],
  "upvotes": 4,
  "downvotes": 0,
  "merge_requests_count": 0,
  "milestone": null,
  "assignee": {
    "name": "Edwardo Grady",
    "username": "keyon",
    "id": 21,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/3e6f06a86cf27fa8b56f3f74f7615987?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/keyon"
  },
  "closed_at": null,
  "closed_by": null,
  "author": {
    "name": "Vivian Hermann",
    "username": "orville",
    "id": 11,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/orville"
  },
  "subscribed": false,
  "due_date": null,
  "web_url": "http://gitlab.example.com/my-group/my-project/issues/12",
  "references": {
    "short": "#12",
    "relative": "#12",
    "full": "my-group/my-project#12"
  },
  "confidential": false,
  "discussion_locked": false,
  "task_completion_status":{
     "count":0,
     "completed_count":0
  }
}

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.

POST /projects/:id/issues/:issue_iid/todo

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/todo"

Example response:

{
  "id": 112,
  "project": {
    "id": 5,
    "name": "GitLab CI/CD",
    "name_with_namespace": "GitLab Org / GitLab CI/CD",
    "path": "gitlab-ci",
    "path_with_namespace": "gitlab-org/gitlab-ci"
  },
  "author": {
    "name": "Administrator",
    "username": "root",
    "id": 1,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/root"
  },
  "action_name": "marked",
  "target_type": "Issue",
  "target": {
    "id": 93,
    "iid": 10,
    "project_id": 5,
    "title": "Vel voluptas atque dicta mollitia adipisci qui at.",
    "description": "Tempora laboriosam sint magni sed voluptas similique.",
    "state": "closed",
    "created_at": "2016-06-17T07:47:39.486Z",
    "updated_at": "2016-07-01T11:09:13.998Z",
    "labels": [],
    "milestone": {
      "id": 26,
      "iid": 1,
      "project_id": 5,
      "title": "v0.0",
      "description": "Accusantium nostrum rerum quae quia quis nesciunt suscipit id.",
      "state": "closed",
      "created_at": "2016-06-17T07:47:33.832Z",
      "updated_at": "2016-06-17T07:47:33.832Z",
      "due_date": null
    },
    "assignees": [{
      "name": "Jarret O'Keefe",
      "username": "francisca",
      "id": 14,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/francisca"
    }],
    "assignee": {
      "name": "Jarret O'Keefe",
      "username": "francisca",
      "id": 14,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/francisca"
    },
    "author": {
      "name": "Maxie Medhurst",
      "username": "craig_rutherford",
      "id": 12,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/craig_rutherford"
    },
    "subscribed": true,
    "user_notes_count": 7,
    "upvotes": 0,
    "downvotes": 0,
    "merge_requests_count": 0,
    "due_date": null,
    "web_url": "http://gitlab.example.com/my-group/my-project/issues/10",
    "references": {
      "short": "#10",
      "relative": "#10",
      "full": "my-group/my-project#10"
    },
    "confidential": false,
    "discussion_locked": false,
    "task_completion_status":{
       "count":0,
       "completed_count":0
    }
  },
  "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/issues/10",
  "body": "Vel voluptas atque dicta mollitia adipisci qui at.",
  "state": "pending",
  "created_at": "2016-07-01T11:09:13.992Z"
}

DANGER: Deprecated: The assignee column is deprecated. We now show it as a single-sized array assignees to conform to the GitLab EE API.

NOTE: Note: The closed_by attribute was introduced in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists.

Set a time estimate for an issue

Sets an estimated time of work for this issue.

POST /projects/:id/issues/:issue_iid/time_estimate

Attribute	Type	Required	Description
duration	string	yes	The duration in human format. e.g: 3h30m
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m"

Example response:

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

Reset the time estimate for an issue

Resets the estimated time for this issue to 0 seconds.

POST /projects/:id/issues/:issue_iid/reset_time_estimate

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate"

Example response:

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

Add spent time for an issue

Adds spent time for this issue

POST /projects/:id/issues/:issue_iid/add_spent_time

Attribute	Type	Required	Description
duration	string	yes	The duration in human format. e.g: 3h30m
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h"

Example response:

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

Reset spent time for an issue

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

POST /projects/:id/issues/:issue_iid/reset_spent_time

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time"

Example response:

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

Get time tracking stats

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.

GET /projects/:id/issues/:issue_iid/time_stats

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats"

Example response:

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

List merge requests related to issue

Get 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.

GET /projects/:id/issues/:issue_id/related_merge_requests

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests"

Example response:

[
  {
    "id": 29,
    "iid": 11,
    "project_id": 1,
    "title": "Provident eius eos blanditiis consequatur neque odit.",
    "description": "Ut consequatur ipsa aspernatur quisquam voluptatum fugit. Qui harum corporis quo fuga ut incidunt veritatis. Autem necessitatibus et harum occaecati nihil ea.\r\n\r\ntwitter/flight#8",
    "state": "opened",
    "created_at": "2018-09-18T14:36:15.510Z",
    "updated_at": "2018-09-19T07:45:13.089Z",
    "closed_by": null,
    "closed_at": null,
    "target_branch": "v2.x",
    "source_branch": "so_long_jquery",
    "user_notes_count": 9,
    "upvotes": 0,
    "downvotes": 0,
    "author": {
      "id": 14,
      "name": "Verna Hills",
      "username": "lawanda_reinger",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/de68a91aeab1cff563795fb98a0c2cc0?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/lawanda_reinger"
    },
    "assignee": {
      "id": 19,
      "name": "Jody Baumbach",
      "username": "felipa.kuvalis",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/6541fc75fc4e87e203529bd275fafd07?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/felipa.kuvalis"
    },
    "source_project_id": 1,
    "target_project_id": 1,
    "labels": [],
    "work_in_progress": false,
    "milestone": {
      "id": 27,
      "iid": 2,
      "project_id": 1,
      "title": "v1.0",
      "description": "Et tenetur voluptatem minima doloribus vero dignissimos vitae.",
      "state": "active",
      "created_at": "2018-09-18T14:35:44.353Z",
      "updated_at": "2018-09-18T14:35:44.353Z",
      "due_date": null,
      "start_date": null,
      "web_url": "https://gitlab.example.com/twitter/flight/milestones/2"
    },
    "merge_when_pipeline_succeeds": false,
    "merge_status": "cannot_be_merged",
    "sha": "3b7b528e9353295c1c125dad281ac5b5deae5f12",
    "merge_commit_sha": null,
    "squash_commit_sha": null,
    "discussion_locked": null,
    "should_remove_source_branch": null,
    "force_remove_source_branch": false,
    "reference": "!11",
    "web_url": "https://gitlab.example.com/twitter/flight/merge_requests/4",
    "references": {
      "short": "!4",
      "relative": "!4",
      "full": "twitter/flight!4"
    },
    "time_stats": {
      "time_estimate": 0,
      "total_time_spent": 0,
      "human_time_estimate": null,
      "human_total_time_spent": null
    },
    "squash": false,
    "task_completion_status": {
      "count": 0,
      "completed_count": 0
    },
    "changes_count": "10",
    "latest_build_started_at": "2018-12-05T01:16:41.723Z",
    "latest_build_finished_at": "2018-12-05T02:35:54.046Z",
    "first_deployed_to_production_at": null,
    "pipeline": {
      "id": 38980952,
      "sha": "81c6a84c7aebd45a1ac2c654aa87f11e32338e0a",
      "ref": "test-branch",
      "status": "success",
      "web_url": "https://gitlab.com/gitlab-org/gitlab/pipelines/38980952"
    },
    "head_pipeline": {
      "id": 38980952,
      "sha": "81c6a84c7aebd45a1ac2c654aa87f11e32338e0a",
      "ref": "test-branch",
      "status": "success",
      "web_url": "https://gitlab.example.com/twitter/flight/pipelines/38980952",
      "before_sha": "3c738a37eb23cf4c0ed0d45d6ddde8aad4a8da51",
      "tag": false,
      "yaml_errors": null,
      "user": {
        "id": 19,
        "name": "Jody Baumbach",
        "username": "felipa.kuvalis",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/6541fc75fc4e87e203529bd275fafd07?s=80&d=identicon",
        "web_url": "https://gitlab.example.com/felipa.kuvalis"
      },
      "created_at": "2018-12-05T01:16:13.342Z",
      "updated_at": "2018-12-05T02:35:54.086Z",
      "started_at": "2018-12-05T01:16:41.723Z",
      "finished_at": "2018-12-05T02:35:54.046Z",
      "committed_at": null,
      "duration": 4436,
      "coverage": "46.68",
      "detailed_status": {
        "icon": "status_warning",
        "text": "passed",
        "label": "passed with warnings",
        "group": "success-with-warnings",
        "tooltip": "passed",
        "has_details": true,
        "details_path": "/twitter/flight/pipelines/38",
        "illustration": null,
        "favicon": "https://gitlab.example.com/assets/ci_favicons/favicon_status_success-8451333011eee8ce9f2ab25dc487fe24a8758c694827a582f17f42b0a90446a2.png"
      }
    },
    "diff_refs": {
      "base_sha": "d052d768f0126e8cddf80afd8b1eb07f406a3fcb",
      "head_sha": "81c6a84c7aebd45a1ac2c654aa87f11e32338e0a",
      "start_sha": "d052d768f0126e8cddf80afd8b1eb07f406a3fcb"
    },
    "merge_error": null,
    "user": {
      "can_merge": true
    }
  }
]

List merge requests that will close issue on merge

Get all the merge requests that will close an 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.

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

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project issue

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by"

Example response:

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

Participants on issues

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.

GET /projects/:id/issues/:issue_iid/participants

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/participants"

Example response:

[
  {
    "id": 1,
    "name": "John Doe1",
    "username": "user1",
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
    "web_url": "http://gitlab.example.com/user1"
  },
  {
    "id": 5,
    "name": "John Doe5",
    "username": "user5",
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80&d=identicon",
    "web_url": "http://gitlab.example.com/user5"
  }
]

Comments on issues

Comments are done via the notes resource.

Get user agent details

Available only for admins.

GET /projects/:id/issues/:issue_iid/user_agent_detail

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project owned by the authenticated user
issue_iid	integer	yes	The internal ID of a project's issue

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/user_agent_detail"

Example response:

{
  "user_agent": "AppleWebKit/537.36",
  "ip_address": "127.0.0.1",
  "akismet_submitted": false
}

List issue state events

To track which state was set, who did it, and when it happened, check out Resource state events API.