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
| Name | Type | Description |
|---|---|---|
with_Query | Boolean | If true,name,color,description,description_,text_Default: false |
stateQuery | String | Filter issues by state Allowed values: opened,closed,allDefault: all |
closed_Query | Integer | Return issues closed by the user with the given ID |
order_Query | String | Sort results by the specified field Allowed values: created_,due_,label_,milestone_,popularity,priority,relative_,title,updated_Default: created_ |
sortQuery | String | Sort results in ascending or descending order Allowed values: asc,descDefault: desc |
due_Query | String | Return issues that have no due date, Allowed values: 0,any,today,tomorrow,overdue,week,month,next_, |
issue_Query | String | The type of the issue. Allowed values: issue,incident,test_,requirement,task,ticket |
labelsQuery | Array of strings | Comma-None means no labels are assigned.Any means at least one label is assigned.No+Label (deprecated) means no labels are assigned. |
milestoneQuery | String | Milestone title.None lists all issues with no milestone.Any lists all issues that have an assigned milestone.None and Any is planned for removal.milestone_ attribute instead.milestone_ |
milestone_Query | String | Return issues assigned to milestones with a given timebox value.None lists all issues with no milestone.Any lists all issues that have an assigned milestone.Upcoming lists all issues assigned to milestones due in the future.Started lists all issues assigned to open,Upcoming and Started differs from the logic used in the GraphmilestoneAllowed values: Any,None,Upcoming,Started |
iidsQuery | Array of integers | Return only the issues having the given iid |
searchQuery | String | Search issues against their title and description |
inQuery | String | Modify the scope of the search attribute to title,description,title,.title, |
author_Query | Integer | Return issues created by the given user ID.scope=all or scope=assigned_.author_ |
author_Query | String | Return issues created by the given username.author_ |
assignee_Query | Integer or string | Return issues assigned to the given user id.None returns unassigned issues and Any returns issues with an assignee.assignee_ |
assignee_Query | Array of strings | Return issues assigned to the given username.assignee_ |
created_Query | String (date- | Return issues created on or after the specified time |
created_Query | String (date- | Return issues created on or before the specified time |
updated_Query | String (date- | Return issues updated on or after the specified time |
updated_Query | String (date- | Return issues updated on or before the specified time |
notQuery | Object | Return issues that do not match the specified parameters |
not[labels]Query | Array of strings | Comma- |
not[milestone]Query | String | Milestone title.not[milestone_ |
not[milestone_Query | String | Return issues assigned to milestones without the specified timebox value.not[milestone]Allowed values: Any,None,Upcoming,Started |
not[iids]Query | Array of integers | Internal IDs of issues to exclude |
not[author_Query | Integer | Return issues not authored by the user with the given ID.not[author_ |
not[author_Query | String | Return issues not authored by the user with the given username.not[author_ |
not[assignee_Query | Integer | Return issues not assigned to the user with the given ID.not[assignee_ |
not[assignee_Query | Array of strings | Return issues not assigned to the user with the given username.not[assignee_ |
scopeQuery | String | Return issues for the given scope Allowed values: created-,assigned-,created_,assigned_,allDefault: created_ |
my_Query | String | Return issues reacted to by the authenticated user with the given emoji.None returns issues with no reaction and Any returns issues with at least one reaction |
confidentialQuery | Boolean | If true,false, |
pageQuery | Integer | Page number of results to retrieve Default: 1Example: 1 |
per_Query | Integer | Number of items to list per page Default: 20Example: 20 |
non_Query | Boolean | If true,false,Default: true |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
Retrieve an issue
GET /api/v4/issues/{id}
Retrieves a specified issue. Administrators only.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String | ID of the issue |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not 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
| Name | Type | Description |
|---|---|---|
labelsQuery | Array of strings | Comma-None means no labels are assigned.Any means at least one label is assigned.No+Label (deprecated) means no labels are assigned. |
milestoneQuery | String | Milestone title.None lists all issues with no milestone.Any lists all issues that have an assigned milestone.None and Any is planned for removal.milestone_ attribute instead.milestone_ |
milestone_Query | String | Return issues assigned to milestones with a given timebox value.None lists all issues with no milestone.Any lists all issues that have an assigned milestone.Upcoming lists all issues assigned to milestones due in the future.Started lists all issues assigned to open,Upcoming and Started differs from the logic used in the GraphmilestoneAllowed values: Any,None,Upcoming,Started |
iidsQuery | Array of integers | Return only the issues having the given iid |
searchQuery | String | Search issues against their title and description |
inQuery | String | Modify the scope of the search attribute to title,description,title,.title, |
author_Query | Integer | Return issues created by the given user ID.scope=all or scope=assigned_.author_ |
author_Query | String | Return issues created by the given username.author_ |
assignee_Query | Integer or string | Return issues assigned to the given user id.None returns unassigned issues and Any returns issues with an assignee.assignee_ |
assignee_Query | Array of strings | Return issues assigned to the given username.assignee_ |
created_Query | String (date- | Return issues created on or after the specified time |
created_Query | String (date- | Return issues created on or before the specified time |
updated_Query | String (date- | Return issues updated on or after the specified time |
updated_Query | String (date- | Return issues updated on or before the specified time |
notQuery | Object | Return issues that do not match the specified parameters |
not[labels]Query | Array of strings | Comma- |
not[milestone]Query | String | Milestone title.not[milestone_ |
not[milestone_Query | String | Return issues assigned to milestones without the specified timebox value.not[milestone]Allowed values: Any,None,Upcoming,Started |
not[iids]Query | Array of integers | Internal IDs of issues to exclude |
not[author_Query | Integer | Return issues not authored by the user with the given ID.not[author_ |
not[author_Query | String | Return issues not authored by the user with the given username.not[author_ |
not[assignee_Query | Integer | Return issues not assigned to the user with the given ID.not[assignee_ |
not[assignee_Query | Array of strings | Return issues not assigned to the user with the given username.not[assignee_ |
scopeQuery | String | Return issues for the given scope Allowed values: created_,assigned_,allDefault: created_ |
my_Query | String | Return issues reacted to by the authenticated user with the given emoji.None returns issues with no reaction and Any returns issues with at least one reaction |
confidentialQuery | Boolean | If true,false, |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
400 | Bad 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | The internal ID of the issue |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
durationRequired | String | The duration in human format |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
List all issue links
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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | Internal ID of the issue |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | Array of APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Create an issue link
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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | Internal ID of the issue |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
link_ | String | The type of the relation Allowed values: relates_Default: relates_ |
target_Required | String or integer | Internal ID of the issue in the target project |
target_Required | String or integer | ID or URL- |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not Found | — |
Retrieve an issue link
GET /api/v4/projects/{id}/issues/{issue_iid}/links/{issue_link_id}
Retrieves a specified issue link.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | Internal ID of the issue |
issue_Path, | String or integer | ID of the issue relationship |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Delete an issue link
DELETE /api/v4/projects/{id}/issues/{issue_iid}/links/{issue_link_id}
Deletes a specified issue link, removing the two-way relationship.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | Internal ID of the issue |
issue_Path, | String or integer | ID of the issue relationship |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | Internal ID of the issue |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
List all merge requests related to an issue
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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | Internal ID of the issue |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | The internal ID of the issue |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | The internal ID of the issue |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | The internal ID of the issue |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
durationRequired | String | The duration in human format Example: 3h30m |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad request | — |
401 | Unauthorized | — |
404 | Not 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | The internal ID of the issue |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not 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
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | ID or URL- |
issue_Path, | Integer | Internal ID of the issue |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesCustomAttribute
| Property | Type | Description |
|---|---|---|
key | String | Example:foo |
value | String | Example:bar |
APIEntitiesIssuableReferences
| Property | Type | Description |
|---|---|---|
full | String | Example:test&6 |
relative | String | Example:&6 |
short | String | Example:&6 |
APIEntitiesIssuableTimeStats
| Property | Type | Description |
|---|---|---|
human_ | String | Example:3h 30m |
human_ | String | Example:1h |
time_ | Integer | Example:12600 |
total_ | Integer | Example:3600 |
APIEntitiesIssue
| Property | Type | Description |
|---|---|---|
_ | Object | — |
_ | String | Example:http: |
_ | String | Example:http: |
_ | String | Example:http: |
_ | String | Example:http: |
_ | String | Example:http: |
assignee | APIEntities | — |
assignees | APIEntities | — |
author | APIEntities | — |
closed_ | String (date- | Example:2022- |
closed_ | APIEntities | — |
confidential | Boolean | — |
created_ | String (date- | Example:2022- |
description | String | Example:Repellendus impedit et vel velit dignissimos. |
discussion_ | Boolean | — |
downvotes | Integer | — |
due_ | String (date) | Example:2022- |
has_ | Boolean | Example:true |
id | Integer (int64) | Example:84 |
iid | Integer | Example:14 |
imported | Boolean | Example:false |
imported_ | String | Example:github |
issue_ | String | Example:issue |
labels | Array of strings | Example:["bug"] |
merge_ | Integer | — |
milestone | APIEntities | — |
moved_ | Integer (int64) | Example:1 |
project_ | Integer (int64) | Example:4 |
references | APIEntities | — |
service_ | String | Example:user@example. |
severity | String | The severity of the issue Allowed values: UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL |
start_ | String (date) | Example:2022- |
state | String | Example:closed |
subscribed | Boolean | Example:false |
task_ | APIEntities | — |
task_ | String | Example:2 of 4 tasks completed |
time_ | APIEntities | — |
title | String | Example:Impedit et ut et dolores vero provident ullam est |
type | String | The type of the issue Allowed values: ISSUE,INCIDENT,TEST_,REQUIREMENT,TASK,TICKETExample: ISSUE |
updated_ | String (date- | Example:2022- |
upvotes | Integer | — |
user_ | Integer | — |
web_ | String | Example:http: |
APIEntitiesIssueBasic
| Property | Type | Description |
|---|---|---|
assignee | APIEntities | — |
assignees | APIEntities | — |
author | APIEntities | — |
closed_ | String (date- | Example:2022- |
closed_ | APIEntities | — |
confidential | Boolean | — |
created_ | String (date- | Example:2022- |
description | String | Example:Repellendus impedit et vel velit dignissimos. |
discussion_ | Boolean | — |
downvotes | Integer | — |
due_ | String (date) | Example:2022- |
id | Integer (int64) | Example:84 |
iid | Integer | Example:14 |
issue_ | String | Example:issue |
labels | Array of strings | Example:["bug"] |
merge_ | Integer | — |
milestone | APIEntities | — |
project_ | Integer (int64) | Example:4 |
start_ | String (date) | Example:2022- |
state | String | Example:closed |
task_ | APIEntities | — |
time_ | APIEntities | — |
title | String | Example:Impedit et ut et dolores vero provident ullam est |
type | String | The type of the issue Allowed values: ISSUE,INCIDENT,TEST_,REQUIREMENT,TASK,TICKETExample: ISSUE |
updated_ | String (date- | Example:2022- |
upvotes | Integer | — |
user_ | Integer | — |
web_ | String | Example:http: |
APIEntitiesIssueLink
| Property | Type | Description |
|---|---|---|
id | Integer (int64) | Example:1 |
link_ | String | Example:relates_ |
source_ | APIEntities | — |
target_ | APIEntities | — |
APIEntitiesMergeRequestAuthor
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:/ |
avatar_ | String | Example:https: |
bot | Boolean | Example:false |
custom_ | Array of APIEntities | — |
id | Integer (int64) | Example:1 |
locked | Boolean | — |
name | String | Example:Administrator |
public_ | String | Example:john@example. |
state | String | Example:active |
username | String | Example:admin |
web_ | String | Example:https: |
APIEntitiesMergeRequestBasic
| Property | Type | Description |
|---|---|---|
allow_ | Boolean | — |
allow_ | Boolean | — |
assignee | APIEntities | — |
assignees | APIEntities | — |
author | APIEntities | — |
blocking_ | Boolean | — |
closed_ | String (date- | Example:2022- |
closed_ | APIEntities | — |
created_ | String (date- | Example:2022- |
description | String | Example:Repellendus impedit et vel velit dignissimos. |
description_ | String | — |
detailed_ | String | Example:mergeable |
discussion_ | Boolean | — |
downvotes | Integer | — |
draft | Boolean | — |
force_ | Boolean | — |
has_ | Boolean | — |
id | Integer (int64) | Example:84 |
iid | Integer | Example:14 |
imported | Boolean | — |
imported_ | String | Example:bitbucket |
labels | Array of strings | — |
merge_ | String (date- | Example:2022- |
merge_ | String | Example:1234abcd |
merge_ | String | Example:unchecked |
merge_ | APIEntities | — |
merge_ | Boolean | — |
merged_ | String (date- | Example:2022- |
merged_ | APIEntities | — |
milestone | APIEntities | — |
prepared_ | String (date- | Example:2022- |
project_ | Integer (int64) | Example:4 |
reference | String | Example:!1 |
references | APIEntities | — |
reviewers | APIEntities | — |
sha | String | Example:1234abcd |
should_ | Boolean | — |
source_ | String | — |
source_ | Integer (int64) | — |
squash | Boolean | — |
squash_ | String | Example:1234abcd |
squash_ | Boolean | — |
state | String | Example:closed |
target_ | String | — |
target_ | Integer (int64) | — |
task_ | APIEntities | — |
time_ | APIEntities | — |
title | String | Example:Impedit et ut et dolores vero provident ullam est |
title_ | String | — |
updated_ | String (date- | Example:2022- |
upvotes | Integer | — |
user_ | Integer | — |
web_ | String | Example:https: |
work_ | Boolean | — |
APIEntitiesMilestone
| Property | Type | Description |
|---|---|---|
created_ | String | — |
description | String | — |
due_ | String | — |
expired | Boolean | — |
group_ | String | — |
id | Integer (int64) | — |
iid | Integer (int64) | — |
project_ | Integer (int64) | — |
start_ | String | — |
state | String | — |
title | String | — |
updated_ | String | — |
web_ | String | — |
APIEntitiesRelatedIssue
| Property | Type | Description |
|---|---|---|
_ | Object | — |
_ | String | Example:http: |
_ | String | Example:http: |
_ | String | Example:http: |
_ | String | Example:http: |
_ | String | Example:http: |
assignee | APIEntities | — |
assignees | APIEntities | — |
author | APIEntities | — |
closed_ | String (date- | Example:2022- |
closed_ | APIEntities | — |
confidential | Boolean | — |
created_ | String (date- | Example:2022- |
description | String | Example:Repellendus impedit et vel velit dignissimos. |
discussion_ | Boolean | — |
downvotes | Integer | — |
due_ | String (date) | Example:2022- |
has_ | Boolean | Example:true |
id | Integer (int64) | Example:84 |
iid | Integer | Example:14 |
imported | Boolean | Example:false |
imported_ | String | Example:github |
issue_ | Integer (int64) | Example:1 |
issue_ | String | Example:issue |
labels | Array of strings | Example:["bug"] |
link_ | String (date- | Example:2022- |
link_ | String | Example:relates_ |
link_ | String (date- | Example:2022- |
merge_ | Integer | — |
milestone | APIEntities | — |
moved_ | Integer (int64) | Example:1 |
project_ | Integer (int64) | Example:4 |
references | APIEntities | — |
service_ | String | Example:user@example. |
severity | String | The severity of the issue Allowed values: UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL |
start_ | String (date) | Example:2022- |
state | String | Example:closed |
subscribed | Boolean | Example:false |
task_ | APIEntities | — |
task_ | String | Example:2 of 4 tasks completed |
time_ | APIEntities | — |
title | String | Example:Impedit et ut et dolores vero provident ullam est |
type | String | The type of the issue Allowed values: ISSUE,INCIDENT,TEST_,REQUIREMENT,TASK,TICKETExample: ISSUE |
updated_ | String (date- | Example:2022- |
upvotes | Integer | — |
user_ | Integer | — |
web_ | String | Example:http: |
APIEntitiesTaskCompletionStatus
| Property | Type | Description |
|---|---|---|
completed_ | Integer | Example:3 |
count | Integer | Example:5 |
APIEntitiesUserAgentDetail
| Property | Type | Description |
|---|---|---|
akismet_ | Boolean | Example:false |
ip_ | String | Example:127. |
user_ | String | Example:Apple |
APIEntitiesUserBasic
| Property | Type | Description |
|---|---|---|
avatar_ | String | Example:/ |
avatar_ | String | Example:https: |
custom_ | Array of APIEntities | — |
id | Integer (int64) | Example:1 |
locked | Boolean | — |
name | String | Example:Administrator |
public_ | String | Example:john@example. |
state | String | Example:active |
username | String | Example:admin |
web_ | String | Example:https: |