Use this API to manage issues, their links to related issues, and issue statistics. You can:

  • Create, update, and delete issues.
  • Manage issue metadata, like assignees, labels, milestones, and time tracking.
  • Cross-reference issues and merge requests.
  • Track issue movement and promotion between projects and epics.
  • Retrieve statistics about issues.

If a user is not a member of a private project, a GET request on that project results in a 404 status code.

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 all issues for the currently authenticated user

GET /api/v4/issues

Lists all issues accessible by the currently authenticated user. By default, returns only issues created by the current user. To list all issues, use parameter scope=all.

Parameters

NameTypeDescription
with_labels_details
Query		BooleanReturn titles of labels and other details
Default: false
state
Query		StringReturn opened, closed, or all issues
Allowed values: opened, closed, all
Default: all
closed_by_id
Query		IntegerReturn issues which were closed by the user with the given ID
order_by
Query		StringReturn issues ordered by created_at, due_date, label_priority, milestone_due, popularity, priority, relative_position, title, or updated_at fields
Allowed values: created_at, due_date, label_priority, milestone_due, popularity, priority, relative_position, title, updated_at
Default: created_at
sort
Query		StringReturn issues sorted in asc or desc order
Allowed values: asc, desc
Default: desc
due_date
Query		StringReturn 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: overdue, week, month, next_month_and_previous_two_weeks, 0
Allowed values: 0, any, today, tomorrow, overdue, week, month, next_month_and_previous_two_weeks, ``
issue_type
Query		StringThe type of the issue. Accepts: issue, incident, test_case, requirement, task, ticket
Allowed values: issue, incident, test_case, requirement, task, ticket
labels
Query		Array of stringsComma-separated list of label names
milestone
Query		StringMilestone title. Mutually exclusive with milestone_id
milestone_id
Query		StringReturn issues assigned to milestones with the specified timebox value (“Any”, “None”, “Upcoming” or “Started”). Mutually exclusive with milestone
Allowed values: Any, None, Upcoming, Started
iids
Query		Array of integersThe IID array of issues
search
Query		StringSearch issues for text present in the title, description, or any combination of these
in
Query		Stringtitle, description, or a string joining them with comma
author_id
Query		IntegerReturn issues which are authored by the user with the given ID. Mutually exclusive with author_username
author_username
Query		StringReturn issues which are authored by the user with the given username. Mutually exclusive with author_id
assignee_id
Query		Integer or stringReturn issues which are assigned to the user with the given ID. Mutually exclusive with assignee_username
assignee_username
Query		Array of stringsReturn issues which are assigned to the user with the given username. Mutually exclusive with assignee_id
created_after
Query		String (date-time)Return issues created after the specified time
created_before
Query		String (date-time)Return issues created before the specified time
updated_after
Query		String (date-time)Return issues updated after the specified time
updated_before
Query		String (date-time)Return issues updated before the specified time
not
Query		ObjectFilters by the specified parameters
not[labels]
Query		Array of stringsComma-separated list of label names
not[milestone]
Query		StringMilestone title. Mutually exclusive with not[milestone_id]
not[milestone_id]
Query		StringReturn issues assigned to milestones without the specified timebox value (“Any”, “None”, “Upcoming” or “Started”). Mutually exclusive with not[milestone]
Allowed values: Any, None, Upcoming, Started
not[iids]
Query		Array of integersThe IID array of issues
not[author_id]
Query		IntegerReturn issues which are not authored by the user with the given ID. Mutually exclusive with not[author_username]
not[author_username]
Query		StringReturn issues which are not authored by the user with the given username. Mutually exclusive with not[author_id]
not[assignee_id]
Query		IntegerReturn issues which are not assigned to the user with the given ID. Mutually exclusive with not[assignee_username]
not[assignee_username]
Query		Array of stringsReturn issues which are not assigned to the user with the given username. Mutually exclusive with not[assignee_id]
scope
Query		StringReturn issues for the given scope: created_by_me, assigned_to_me or all
Allowed values: created-by-me, assigned-to-me, created_by_me, assigned_to_me, all
Default: created_by_me
my_reaction_emoji
Query		StringReturn issues reacted by the authenticated user by the given emoji
confidential
Query		BooleanFilter confidential or public issues
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20
non_archived
Query		BooleanReturn issues from non archived projects
Default: true

Responses

CodeDescriptionSchema
200OKAPIEntitiesIssue
400Bad Request—

Retrieve an issue

GET /api/v4/issues/{id}

Retrieves a specified issue. Administrators only.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of the Issue

Responses

CodeDescriptionSchema
200OKAPIEntitiesIssue
400Bad Request—
404Not Found—

Retrieve issues statistics for the currently authenticated user

GET /api/v4/issues_statistics

Retrieves statistics for issues accessible by the currently authenticated user. By default, returns only issues created by the current user. To get all issues, set the scope attribute to all.

Parameters

NameTypeDescription
labels
Query		Array of stringsComma-separated list of label names
milestone
Query		StringMilestone title. Mutually exclusive with milestone_id
milestone_id
Query		StringReturn issues assigned to milestones with the specified timebox value (“Any”, “None”, “Upcoming” or “Started”). Mutually exclusive with milestone
Allowed values: Any, None, Upcoming, Started
iids
Query		Array of integersThe IID array of issues
search
Query		StringSearch issues for text present in the title, description, or any combination of these
in
Query		Stringtitle, description, or a string joining them with comma
author_id
Query		IntegerReturn issues which are authored by the user with the given ID. Mutually exclusive with author_username
author_username
Query		StringReturn issues which are authored by the user with the given username. Mutually exclusive with author_id
assignee_id
Query		Integer or stringReturn issues which are assigned to the user with the given ID. Mutually exclusive with assignee_username
assignee_username
Query		Array of stringsReturn issues which are assigned to the user with the given username. Mutually exclusive with assignee_id
created_after
Query		String (date-time)Return issues created after the specified time
created_before
Query		String (date-time)Return issues created before the specified time
updated_after
Query		String (date-time)Return issues updated after the specified time
updated_before
Query		String (date-time)Return issues updated before the specified time
not
Query		ObjectFilters by the specified parameters
not[labels]
Query		Array of stringsComma-separated list of label names
not[milestone]
Query		StringMilestone title. Mutually exclusive with not[milestone_id]
not[milestone_id]
Query		StringReturn issues assigned to milestones without the specified timebox value (“Any”, “None”, “Upcoming” or “Started”). Mutually exclusive with not[milestone]
Allowed values: Any, None, Upcoming, Started
not[iids]
Query		Array of integersThe IID array of issues
not[author_id]
Query		IntegerReturn issues which are not authored by the user with the given ID. Mutually exclusive with not[author_username]
not[author_username]
Query		StringReturn issues which are not authored by the user with the given username. Mutually exclusive with not[author_id]
not[assignee_id]
Query		IntegerReturn issues which are not assigned to the user with the given ID. Mutually exclusive with not[assignee_username]
not[assignee_username]
Query		Array of stringsReturn issues which are not assigned to the user with the given username. Mutually exclusive with not[assignee_id]
scope
Query		StringReturn issues for the given scope: created_by_me, assigned_to_me or all
Allowed values: created_by_me, assigned_to_me, all
Default: created_by_me
my_reaction_emoji
Query		StringReturn issues reacted by the authenticated user by the given emoji
confidential
Query		BooleanFilter confidential or public issues

Responses

CodeDescriptionSchema
200OK—
400Bad Request—

Add spent time for an issue

POST /api/v4/projects/{id}/issues/{issue_iid}/add_spent_time

Adds spent time for a specified issue.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
issue_iid
Path, required		IntegerThe internal ID of the issue

Request body (application/json)

PropertyTypeDescription
duration
Required		StringThe duration in human format

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesIssuableTimeStats
400Bad Request—
401Unauthorized—
404Not found—

GET /api/v4/projects/{id}/issues/{issue_iid}/links

Lists all linked issues for a specified issue, sorted by the relationship creation datetime (ascending). Issues are filtered according to the user authorizations.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project owned by the authenticated user
issue_iid
Path, required		IntegerThe internal ID of a project’s issue

Responses

CodeDescriptionSchema
200OKAPIEntitiesRelatedIssue
400Bad Request—
401Unauthorized—
404Not found—

POST /api/v4/projects/{id}/issues/{issue_iid}/links

Creates a two-way relationship between two issues. The user must be allowed to update both issues to succeed.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project owned by the authenticated user
issue_iid
Path, required		IntegerThe internal ID of a project’s issue

Request body (application/json)

PropertyTypeDescription
link_typeStringThe type of the relation (“relates_to”, “blocks”, “is_blocked_by”),defaults to “relates_to”)
Allowed values: relates_to
target_issue_iid
Required		String or integerThe internal ID of a target project’s issue
target_project_id
Required		String or integerThe ID or URL-encoded path of a target project

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesIssueLink
400Bad Request—
401Unauthorized—
404Not Found—

GET /api/v4/projects/{id}/issues/{issue_iid}/links/{issue_link_id}

Retrieves a specified issue link.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project owned by the authenticated user
issue_iid
Path, required		IntegerThe internal ID of a project’s issue
issue_link_id
Path, required		String or integerID of an issue relationship

Responses

CodeDescriptionSchema
200OKAPIEntitiesIssueLink
400Bad Request—
401Unauthorized—
404Not found—

DELETE /api/v4/projects/{id}/issues/{issue_iid}/links/{issue_link_id}

Deletes a specified issue link, removing the two-way relationship.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project owned by the authenticated user
issue_iid
Path, required		IntegerThe internal ID of a project’s issue
issue_link_id
Path, required		String or integerThe ID of an issue relationship

Responses

CodeDescriptionSchema
200OKAPIEntitiesIssueLink
400Bad Request—
401Unauthorized—
404Not found—

List all participants in an issue

GET /api/v4/projects/{id}/issues/{issue_iid}/participants

Lists all users that are participants in a specified issue. If the project is private or the issue is confidential, you need to provide credentials to authorize. In most cases, you should authenticate with a personal access token.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
issue_iid
Path, required		IntegerThe internal ID of a project issue

Responses

CodeDescriptionSchema
200OKAPIEntitiesUserBasic
400Bad Request—
404Not Found—

GET /api/v4/projects/{id}/issues/{issue_iid}/related_merge_requests

Lists all merge requests that are related to a specified issue. If the project is private or the issue is confidential, you need to provide credentials to authorize. In most cases, you should authenticate with a personal access token.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
issue_iid
Path, required		IntegerThe internal ID of a project issue

Responses

CodeDescriptionSchema
200OKAPIEntitiesMergeRequestBasic
400Bad Request—
404Not Found—

Reset spent time for an issue

POST /api/v4/projects/{id}/issues/{issue_iid}/reset_spent_time

Resets the total spent time for a specified issue to 0 seconds.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
issue_iid
Path, required		IntegerThe internal ID of the issue

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesIssuableTimeStats
400Bad Request—
401Unauthorized—
404Not found—

Reset the estimated time for an issue

POST /api/v4/projects/{id}/issues/{issue_iid}/reset_time_estimate

Resets the estimated time for a specified issue to 0 seconds.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
issue_iid
Path, required		IntegerThe internal ID of the issue

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesIssuableTimeStats
400Bad Request—
401Unauthorized—
404Not found—

Set the estimated time for an issue

POST /api/v4/projects/{id}/issues/{issue_iid}/time_estimate

Sets an estimated time of work for a specified issue.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
issue_iid
Path, required		IntegerThe internal ID of the issue

Request body (application/json)

PropertyTypeDescription
duration
Required		StringThe duration in human format
Example: 3h30m

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesIssuableTimeStats
400Bad request—
401Unauthorized—
404Not found—

Retrieve time tracking stats for an issue

GET /api/v4/projects/{id}/issues/{issue_iid}/time_stats

Retrieves time tracking stats for a specified issue, including time estimate and time spent in seconds and human-readable format (for example, 1h 30m).

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
issue_iid
Path, required		IntegerThe internal ID of the issue

Responses

CodeDescriptionSchema
200OKAPIEntitiesIssuableTimeStats
400Bad Request—
401Unauthorized—
404Not found—

Retrieve user agent details for an issue

GET /api/v4/projects/{id}/issues/{issue_iid}/user_agent_detail

Retrieves user agent details for an issue.

Parameters

NameTypeDescription
id
Path, required		String or integerThe ID or URL-encoded path of the project
issue_iid
Path, required		IntegerThe internal ID of a project issue

Responses

CodeDescriptionSchema
200OKAPIEntitiesUserAgentDetail
400Bad Request—
404Not Found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCustomAttribute

PropertyTypeDescription
keyStringExample: foo
valueStringExample: bar

APIEntitiesIssuableReferences

PropertyTypeDescription
fullStringExample: test&6
relativeStringExample: &6
shortStringExample: &6

APIEntitiesIssuableTimeStats

PropertyTypeDescription
human_time_estimateStringExample: 3h 30m
human_total_time_spentStringExample: 1h
time_estimateIntegerExample: 12600
total_time_spentIntegerExample: 3600

APIEntitiesIssue

PropertyTypeDescription
_linksObject—
_links.award_emojiStringExample: http://example.com/api/v4/projects/1/issues/2/award_emoji
_links.closed_as_duplicate_ofStringExample: http://example.com/api/v4/projects/1/issues/75
_links.notesStringExample: http://example.com/api/v4/projects/1/issues/2/notes
_links.projectStringExample: http://example.com/api/v4/projects/1
_links.selfStringExample: http://example.com/api/v4/projects/1/issues/2
assigneeAPIEntitiesUserBasic—
assigneesAPIEntitiesUserBasic—
authorAPIEntitiesUserBasic—
closed_atString (date-time)Example: 2022-11-15T08:30:55.232Z
closed_byAPIEntitiesUserBasic—
confidentialBoolean—
created_atString (date-time)Example: 2022-08-17T12:46:35.053Z
descriptionStringExample: Repellendus impedit et vel velit dignissimos.
discussion_lockedBoolean—
downvotesInteger—
due_dateString (date)Example: 2022-11-20
has_tasksBooleanExample: true
idInteger (int64)Example: 84
iidIntegerExample: 14
importedBooleanExample: false
imported_fromStringExample: github
issue_typeStringExample: issue
labelsArray of stringsExample: ["bug"]
merge_requests_countInteger—
milestoneAPIEntitiesMilestone—
moved_to_idInteger (int64)Example: 1
project_idInteger (int64)Example: 4
referencesAPIEntitiesIssuableReferences—
service_desk_reply_toStringExample: user@example.com
severityStringOne of [“UNKNOWN”, “LOW”, “MEDIUM”, “HIGH”, “CRITICAL”]
start_dateString (date)Example: 2022-11-18
stateStringExample: closed
subscribedBooleanExample: false
task_completion_statusAPIEntitiesTaskCompletionStatus—
task_statusStringExample: 2 of 4 tasks completed
time_statsAPIEntitiesIssuableTimeStats—
titleStringExample: Impedit et ut et dolores vero provident ullam est
typeStringOne of [“ISSUE”, “INCIDENT”, “TEST_CASE”, “REQUIREMENT”, “TASK”, “TICKET”]
Example: ISSUE
updated_atString (date-time)Example: 2022-11-14T17:22:01.470Z
upvotesInteger—
user_notes_countInteger—
web_urlStringExample: http://example.com/example/example/issues/14

APIEntitiesIssueBasic

PropertyTypeDescription
assigneeAPIEntitiesUserBasic—
assigneesAPIEntitiesUserBasic—
authorAPIEntitiesUserBasic—
closed_atString (date-time)Example: 2022-11-15T08:30:55.232Z
closed_byAPIEntitiesUserBasic—
confidentialBoolean—
created_atString (date-time)Example: 2022-08-17T12:46:35.053Z
descriptionStringExample: Repellendus impedit et vel velit dignissimos.
discussion_lockedBoolean—
downvotesInteger—
due_dateString (date)Example: 2022-11-20
idInteger (int64)Example: 84
iidIntegerExample: 14
issue_typeStringExample: issue
labelsArray of stringsExample: ["bug"]
merge_requests_countInteger—
milestoneAPIEntitiesMilestone—
project_idInteger (int64)Example: 4
start_dateString (date)Example: 2022-11-18
stateStringExample: closed
task_completion_statusAPIEntitiesTaskCompletionStatus—
time_statsAPIEntitiesIssuableTimeStats—
titleStringExample: Impedit et ut et dolores vero provident ullam est
typeStringOne of [“ISSUE”, “INCIDENT”, “TEST_CASE”, “REQUIREMENT”, “TASK”, “TICKET”]
Example: ISSUE
updated_atString (date-time)Example: 2022-11-14T17:22:01.470Z
upvotesInteger—
user_notes_countInteger—
web_urlStringExample: http://example.com/example/example/issues/14
PropertyTypeDescription
idInteger (int64)Example: 1
link_typeStringExample: relates_to
source_issueAPIEntitiesIssueBasic—
target_issueAPIEntitiesIssueBasic—

APIEntitiesMergeRequestBasic

PropertyTypeDescription
allow_collaborationBoolean—
allow_maintainer_to_pushBoolean—
assigneeAPIEntitiesUserBasic—
assigneesAPIEntitiesUserBasic—
authorAPIEntitiesUserBasic—
blocking_discussions_resolvedBoolean—
closed_atString (date-time)Example: 2022-01-31T15:10:45.080Z
closed_byAPIEntitiesUserBasic—
created_atString (date-time)Example: 2022-08-17T12:46:35.053Z
descriptionStringExample: Repellendus impedit et vel velit dignissimos.
description_htmlString—
detailed_merge_statusStringExample: mergeable
discussion_lockedBoolean—
downvotesInteger—
draftBoolean—
force_remove_source_branchBoolean—
has_conflictsBoolean—
idInteger (int64)Example: 84
iidIntegerExample: 14
importedBoolean—
imported_fromStringExample: bitbucket
labelsArray of strings—
merge_afterString (date-time)Example: 2022-01-31T15:10:45.080Z
merge_commit_shaStringExample: 1234abcd
merge_statusStringExample: unchecked
merge_userAPIEntitiesUserBasic—
merge_when_pipeline_succeedsBoolean—
merged_atString (date-time)Example: 2022-01-31T15:10:45.080Z
merged_byAPIEntitiesUserBasic—
milestoneAPIEntitiesMilestone—
prepared_atString (date-time)Example: 2022-01-31T15:10:45.080Z
project_idInteger (int64)Example: 4
referenceStringExample: !1
referencesAPIEntitiesIssuableReferences—
reviewersAPIEntitiesUserBasic—
shaStringExample: 1234abcd
should_remove_source_branchBoolean—
source_branchString—
source_project_idInteger (int64)—
squashBoolean—
squash_commit_shaStringExample: 1234abcd
squash_on_mergeBoolean—
stateStringExample: closed
target_branchString—
target_project_idInteger (int64)—
task_completion_statusAPIEntitiesTaskCompletionStatus—
time_statsAPIEntitiesIssuableTimeStats—
titleStringExample: Impedit et ut et dolores vero provident ullam est
title_htmlString—
updated_atString (date-time)Example: 2022-11-14T17:22:01.470Z
upvotesInteger—
user_notes_countInteger—
web_urlStringExample: https://gitlab.example.com/my-group/my-project/-/merge_requests/1
work_in_progressBoolean—

APIEntitiesMilestone

PropertyTypeDescription
created_atString—
descriptionString—
due_dateString—
expiredBoolean—
group_idString—
idInteger (int64)—
iidInteger (int64)—
project_idInteger (int64)—
start_dateString—
stateString—
titleString—
updated_atString—
web_urlString—

APIEntitiesRelatedIssue

PropertyTypeDescription
_linksObject—
_links.award_emojiStringExample: http://example.com/api/v4/projects/1/issues/2/award_emoji
_links.closed_as_duplicate_ofStringExample: http://example.com/api/v4/projects/1/issues/75
_links.notesStringExample: http://example.com/api/v4/projects/1/issues/2/notes
_links.projectStringExample: http://example.com/api/v4/projects/1
_links.selfStringExample: http://example.com/api/v4/projects/1/issues/2
assigneeAPIEntitiesUserBasic—
assigneesAPIEntitiesUserBasic—
authorAPIEntitiesUserBasic—
closed_atString (date-time)Example: 2022-11-15T08:30:55.232Z
closed_byAPIEntitiesUserBasic—
confidentialBoolean—
created_atString (date-time)Example: 2022-08-17T12:46:35.053Z
descriptionStringExample: Repellendus impedit et vel velit dignissimos.
discussion_lockedBoolean—
downvotesInteger—
due_dateString (date)Example: 2022-11-20
has_tasksBooleanExample: true
idInteger (int64)Example: 84
iidIntegerExample: 14
importedBooleanExample: false
imported_fromStringExample: github
issue_link_idInteger (int64)Example: 1
issue_typeStringExample: issue
labelsArray of stringsExample: ["bug"]
link_created_atString (date-time)Example: 2022-01-31T15:10:44.988Z
link_typeStringExample: relates_to
link_updated_atString (date-time)Example: 2022-01-31T15:10:44.988Z
merge_requests_countInteger—
milestoneAPIEntitiesMilestone—
moved_to_idInteger (int64)Example: 1
project_idInteger (int64)Example: 4
referencesAPIEntitiesIssuableReferences—
service_desk_reply_toStringExample: user@example.com
severityStringOne of [“UNKNOWN”, “LOW”, “MEDIUM”, “HIGH”, “CRITICAL”]
start_dateString (date)Example: 2022-11-18
stateStringExample: closed
subscribedBooleanExample: false
task_completion_statusAPIEntitiesTaskCompletionStatus—
task_statusStringExample: 2 of 4 tasks completed
time_statsAPIEntitiesIssuableTimeStats—
titleStringExample: Impedit et ut et dolores vero provident ullam est
typeStringOne of [“ISSUE”, “INCIDENT”, “TEST_CASE”, “REQUIREMENT”, “TASK”, “TICKET”]
Example: ISSUE
updated_atString (date-time)Example: 2022-11-14T17:22:01.470Z
upvotesInteger—
user_notes_countInteger—
web_urlStringExample: http://example.com/example/example/issues/14

APIEntitiesTaskCompletionStatus

PropertyTypeDescription
completed_countIntegerExample: 3
countIntegerExample: 5

APIEntitiesUserAgentDetail

PropertyTypeDescription
akismet_submittedBooleanExample: false
ip_addressStringExample: 127.0.0.1
user_agentStringExample: AppleWebKit/537.36

APIEntitiesUserBasic

PropertyTypeDescription
avatar_pathStringExample: /user/avatar/28/The-Big-Lebowski-400-400.png
avatar_urlStringExample: https://gravatar.com/avatar/1
custom_attributesArray of APIEntitiesCustomAttribute—
idInteger (int64)Example: 1
lockedBoolean—
nameStringExample: Administrator
public_emailStringExample: john@example.com
stateStringExample: active
usernameStringExample: admin
web_urlStringExample: https://gitlab.example.com/root
←
REST API / Invitations
REST API / Jira Connect subscriptions
→