diff options
Diffstat (limited to 'doc/api/issues.md')
| -rw-r--r-- | doc/api/issues.md | 720 |
1 files changed, 448 insertions, 272 deletions
diff --git a/doc/api/issues.md b/doc/api/issues.md index 07678f3ca42..b2c6f0cb739 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues API **(FREE ALL)** @@ -15,13 +15,8 @@ request on that project results in a `404` status code. By default, `GET` requests return 20 results at a time because the API results are paginated. - Read more on [pagination](rest/index.md#pagination). -WARNING: -The `reference` attribute in responses is deprecated in favor of `references`. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.6. - 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. @@ -29,9 +24,7 @@ When requested across groups or projects, it's expected to be the same as the `f ## List issues -> - The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. -> - The `weight` property moved to GitLab Premium in 13.9. -> - The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get all issues the authenticated user has access to. By default it returns only issues created by the current user. To get all issues, @@ -54,41 +47,46 @@ GET /issues?state=closed GET /issues?state=opened ``` +Supported attributes: + | Attribute | Type | Required | Description | |---------------------------------|---------------| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | -| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | -| `epic_id` **(PREMIUM ALL)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `health_status` **(ULTIMATE ALL)** | string | no | Return issues with the specified `health_status`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370721) in GitLab 15.4)._ In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/370721), `None` returns issues with no health status assigned, and `Any` returns issues with a health status assigned. -| `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | -| `iteration_id` **(PREMIUM ALL)** | 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](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `iteration_title` **(PREMIUM ALL)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `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. Using `None` or `Any` will be [deprecated in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/336044). Please use `milestone_id` attribute instead. `milestone` and `milestone_id` are mutually exclusive. | -| `milestone_id` | string | no | Returns issues assigned to milestones with a given timebox value (`None`, `Any`, `Upcoming`, and `Started`). `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. `Upcoming` lists all issues assigned to milestones due in the future. `Started` lists all issues assigned to open, started milestones. `milestone` and `milestone_id` are mutually exclusive. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335939) in GitLab 14.3)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197170) in GitLab 13.0)_ | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, `milestone_id` and `weight`. | -| `order_by` | string | no | Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, `updated_at`, or `weight` fields. Default is `created_at`. | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | -| `search` | string | no | Search issues against their `title` and `description` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | -| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `weight` **(PREMIUM ALL)** | 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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7| +| `assignee_id` | integer | No | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | +| `assignee_username` | string array | No | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | +| `author_id` | integer | No | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | +| `author_username` | string | No | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | +| `confidential` | boolean | No | Filter confidential or public issues. | +| `created_after` | datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `due_date` | string | No | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. | +| `health_status` **(ULTIMATE ALL)** | string | No | Return issues with the specified `health_status`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370721) in GitLab 15.4)._ In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/370721), `None` returns issues with no health status assigned, and `Any` returns issues with a health status assigned. +| `iids[]` | integer array | No | Return only the issues having the given `iid`. | +| `in` | string | No | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description`. | +| `issue_type` | string | No | Filter to a given type of issue. One of `issue`, `incident`, `test_case` or `task`. | +| `iteration_id` **(PREMIUM ALL)** | 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`. | +| `iteration_title` **(PREMIUM ALL)** | string | No | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. | +| `labels` | string | No | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone_id` | string | No | Returns issues assigned to milestones with a given timebox value (`None`, `Any`, `Upcoming`, and `Started`). `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. `Upcoming` lists all issues assigned to milestones due in the future. `Started` lists all issues assigned to open, started milestones. `milestone` and `milestone_id` are mutually exclusive. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335939) in GitLab 14.3)_ | +| `milestone` | string | No | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. Using `None` or `Any` will be [deprecated in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/336044). Use `milestone_id` attribute instead. `milestone` and `milestone_id` are mutually exclusive. | +| `my_reaction_emoji` | string | No | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `non_archived` | boolean | No | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. | +| `not` | Hash | No | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, `milestone_id` and `weight`. | +| `order_by` | string | No | Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, `updated_at`, or `weight` fields. Default is `created_at`. | +| `scope` | string | No | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | +| `search` | string | No | Search issues against their `title` and `description`. | +| `sort` | string | No | Return issues sorted in `asc` or `desc` order. Default is `desc`. | +| `state` | string | No | Return `all` issues or just those that are `opened` or `closed`. | +| `updated_after` | datetime | No | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `updated_before` | datetime | No | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `weight` **(PREMIUM ALL)** | 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`. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/issues" ``` Example response: @@ -254,17 +252,15 @@ to the GitLab EE API. WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## List group issues -> - The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. -> - The `weight` property moved to GitLab Premium in 13.9. -> - The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get a list of a group's issues. -If the group is private, credentials need to be provided for authorization. +If the group is private, you must provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext @@ -284,39 +280,44 @@ GET /groups/:id/issues?state=closed GET /groups/:id/issues?state=opened ``` +Supported attributes: + | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | -| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | -| `epic_id` **(PREMIUM ALL)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `id` | integer/string | yes | The global ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | -| `iteration_id` **(PREMIUM ALL)** | 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](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `iteration_title` **(PREMIUM ALL)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785) 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`. Defaults to `all`. | -| `search` | string | no | Search group issues against their `title` and `description` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `weight` **(PREMIUM ALL)** | 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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `assignee_id` | integer | No | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | +| `assignee_username` | string array | No | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | +| `author_id` | integer | No | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | +| `author_username` | string | No | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | +| `confidential` | boolean | No | Filter confidential or public issues. | +| `created_after` | datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `due_date` | string | No | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. | +| `iids[]` | integer array | No | Return only the issues having the given `iid`. | +| `issue_type` | string | No | Filter to a given type of issue. One of `issue`, `incident`, `test_case` or `task`. | +| `iteration_id` **(PREMIUM ALL)** | 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`. | +| `iteration_title` **(PREMIUM ALL)** | string | No | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. | +| `labels` | string | No | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone` | string | No | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | +| `my_reaction_emoji` | string | No | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `non_archived` | boolean | No | Return issues from non archived projects. Default is true. | +| `not` | Hash | No | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in`. | +| `order_by` | string | No | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | +| `scope` | string | No | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | +| `search` | string | No | Search group issues against their `title` and `description`. | +| `sort` | string | No | Return issues sorted in `asc` or `desc` order. Default is `desc`. | +| `state` | string | No | Return all issues or just those that are `opened` or `closed`. | +| `updated_after` | datetime | No | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `updated_before` | datetime | No | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `weight` **(PREMIUM ALL)** | 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`. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/issues" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/groups/4/issues" ``` Example response: @@ -458,13 +459,11 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## List project issues -> - The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. -> - The `weight` property moved to GitLab Premium in 13.9. -> - The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get a list of a project's issues. @@ -488,38 +487,43 @@ GET /projects/:id/issues?state=closed GET /projects/:id/issues?state=opened ``` +Supported attributes: + | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | -| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | -| `epic_id` **(PREMIUM ALL)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | -| `iteration_id` **(PREMIUM ALL)** | 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](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `iteration_title` **(PREMIUM ALL)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | -| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | -| `search` | string | no | Search project issues against their `title` and `description` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `weight` **(PREMIUM ALL)** | 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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `assignee_id` | integer | No | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | +| `assignee_username` | string array | No | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | +| `author_id` | integer | No | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | +| `author_username` | string | No | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | +| `confidential` | boolean | No | Filter confidential or public issues. | +| `created_after` | datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `due_date` | string | No | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. | +| `iids[]` | integer array | No | Return only the issues having the given `iid`. | +| `issue_type` | string | No | Filter to a given type of issue. One of `issue`, `incident`, `test_case` or `task`. | +| `iteration_id` **(PREMIUM ALL)** | 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`. | +| `iteration_title` **(PREMIUM ALL)** | string | No | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. | +| `labels` | string | No | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone` | string | No | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | +| `my_reaction_emoji` | string | No | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `not` | Hash | No | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in`. | +| `order_by` | string | No | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at`. | +| `scope` | string | No | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | +| `search` | string | No | Search project issues against their `title` and `description`. | +| `sort` | string | No | Return issues sorted in `asc` or `desc` order. Default is `desc`. | +| `state` | string | No | Return all issues or just those that are `opened` or `closed`. | +| `updated_after` | datetime | No | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `updated_before` | datetime | No | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `weight` **(PREMIUM ALL)** | 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`. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues" ``` Example response: @@ -668,11 +672,13 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## Single issue -Only for administrators. Get a single issue. +Only for administrators. + +Get a single issue. The preferred way to do this is by using [personal access tokens](../user/profile/personal_access_tokens.md). @@ -680,12 +686,17 @@ The preferred way to do this is by using [personal access tokens](../user/profil GET /issues/:id ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer | yes | The ID of the issue | +| `id` | integer | Yes | The ID of the issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues/41" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/issues/41" ``` Example response: @@ -831,7 +842,7 @@ to the GitLab EE API. WARNING: The `epic_iid` attribute is deprecated, and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## Single project issue @@ -844,13 +855,18 @@ The preferred way to do this, is by using [personal access tokens](../user/profi GET /projects/:id/issues/:issue_iid ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/41" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/41" ``` Example response: @@ -989,40 +1005,44 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## New issue -> The `weight` property moved to GitLab Premium in 13.9. - Creates a new project issue. ```plaintext POST /projects/:id/issues ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------------------------------------|----------------|----------|--------------| -| `assignee_id` | integer | no | The ID of the user to assign the issue to. Only appears on GitLab Free. | -| `assignee_ids` **(PREMIUM ALL)** | integer array | no | The IDs of the users 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 `YYYY-MM-DD`, for example `2016-03-11` | -| `epic_id` **(PREMIUM ALL)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | -| `epic_iid` **(PREMIUM ALL)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | -| `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | -| `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. To find the `milestone_id` associated with a milestone, view an issue with the milestone assigned and [use the API](#single-project-issue) to retrieve the issue's details. | -| `title` | string | yes | The title of an issue | -| `weight` **(PREMIUM ALL)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `assignee_id` | integer | No | The ID of the user to assign the issue to. Only appears on GitLab Free. | +| `assignee_ids` **(PREMIUM ALL)** | integer array | No | The IDs of the users 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 `YYYY-MM-DD`, for example `2016-03-11`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | +| `epic_iid` **(PREMIUM ALL)** | integer | No | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5). | +| `iid` | integer/string | No | The internal ID of the project's issue (requires administrator or project owner rights). | +| `issue_type` | string | No | The type of issue. One of `issue`, `incident`, `test_case` or `task`. Default is `issue`. | +| `labels` | string | No | Comma-separated label names 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. To find the `milestone_id` associated with a milestone, view an issue with the milestone assigned and [use the API](#single-project-issue) to retrieve the issue's details. | +| `title` | string | Yes | The title of an issue. | +| `weight` **(PREMIUM ALL)** | integer | No | The weight of the issue. Valid values are greater than or equal to 0. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug" ``` Example response: @@ -1137,19 +1157,16 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. -## Rate limits +### Rate limits To help avoid abuse, users can be limited to a specific number of `Create` requests per minute. See [Issues rate limits](../administration/settings/rate_limit_on_issues_creation.md). -## Edit issue - -> The `weight` property moved to GitLab Premium in 13.9. +## Edit an issue -Updates an existing project issue. This call is also used to mark an issue as -closed. +Updates an existing project issue. This request is also used to close or reopen an issue (with `state_event`). At least one of the following parameters is required for the request to be successful: @@ -1170,29 +1187,35 @@ At least one of the following parameters is required for the request to be succe PUT /projects/:id/issues/:issue_iid ``` +Supported attributes: + | 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 users to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | -| `confidential` | boolean | no | Updates an issue to be confidential | -| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | -| `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | -| `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | -| `epic_id` **(PREMIUM ALL)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | -| `epic_iid` **(PREMIUM ALL)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `issue_type` | string | no | Updates the type of issue. One of `issue`, `incident`, or `test_case`. | -| `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` **(PREMIUM ALL)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `add_labels` | string | No | Comma-separated label names to add to an issue. | +| `assignee_ids` | integer array | No | The ID of the users to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | +| `confidential` | boolean | No | Updates an issue to be confidential. | +| `description` | string | No | The description of an issue. Limited to 1,048,576 characters. | +| `discussion_locked` | boolean | No | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | +| `due_date` | string | No | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | +| `epic_iid` **(PREMIUM ALL)** | integer | No | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5). | +| `issue_type` | string | No | Updates the type of issue. One of `issue`, `incident`, `test_case` or `task`. | +| `labels` | string | No | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | +| `milestone_id` | integer | No | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| +| `remove_labels`| string | No | Comma-separated label names to remove from an issue. | +| `state_event` | string | No | The state event of an issue. To close the issue, use `close`, and to reopen it, use `reopen`. | +| `title` | string | No | The title of an issue. | +| `updated_at` | string | No | When the issue was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.| +| `weight` **(PREMIUM ALL)** | integer | No | The weight of the issue. Valid values are greater than or equal to 0. | + +Example request: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close" +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close" ``` Example response: @@ -1311,47 +1334,61 @@ Issues created by users on GitLab Ultimate include the `health_status` property: WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. WARNING: `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. ## Delete an issue -Only for administrators and project owners. Deletes an issue. +Only for administrators and project owners. + +Deletes an issue. ```plaintext DELETE /projects/:id/issues/:issue_iid ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85" +curl --request DELETE \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/85" ``` -## Reorder an issue +If successful, returns [`204 No Content`](rest/index.md#status-codes). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211864) in GitLab 13.2. +## Reorder an issue -Reorders an issue, you can see the results when sorting issues manually +Reorders an issue. You can see the results when [sorting issues manually](../user/project/issues/sorting_issue_lists.md#manual-sorting). ```plaintext PUT /projects/:id/issues/:issue_iid/reorder ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of the project's issue | -| `move_after_id` | integer | no | The global ID of a project's issue that should be placed after this issue | -| `move_before_id` | integer | no | The global ID of a project's issue that should be placed before this issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of the project's issue. | +| `move_after_id` | integer | No | The global ID of a project's issue that should be placed after this issue. | +| `move_before_id` | integer | No | The global ID of a project's issue that should be placed before this issue. | + +Example request: ```shell -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" +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/85/reorder?move_after_id=51&move_before_id=92" ``` ## Move an issue @@ -1367,14 +1404,20 @@ project, it's then assigned to the issue being moved. POST /projects/:id/issues/:issue_iid/move ``` +Supported attributes: + | Attribute | Type | Required | Description | |-----------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) 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 | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) 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. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --form to_project_id=5 "https://gitlab.example.com/api/v4/projects/4/issues/85/move" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --form to_project_id=5 \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/85/move" ``` Example response: @@ -1499,20 +1542,22 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## Clone an issue -Clone the issue to given project. If the user has insufficient permissions, -an error message with status code `400` is returned. - +Clone the issue to given project. Copies as much data as possible as long as the target project contains equivalent -criteria such as labels or milestones. +criteria, such as labels or milestones. + +If you have insufficient permissions, an error message with status code `400` is returned. ```plaintext POST /projects/:id/issues/:issue_iid/clone ``` +Supported attributes: + | Attribute | Type | Required | Description | | --------------- | -------------- | ---------------------- | --------------------------------- | | `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | @@ -1520,9 +1565,12 @@ POST /projects/:id/issues/:issue_iid/clone | `to_project_id` | integer | Yes | ID of the new project. | | `with_notes` | boolean | No | Clone the issue with [notes](notes.md). Default is `false`. | +Example request: + ```shell curl --request POST \ ---header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/1/clone?with_notes=true&to_project_id=6" + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/1/clone?with_notes=true&to_project_id=6" ``` Example response: @@ -1610,7 +1658,11 @@ Example response: } ``` -## Subscribe to an issue +## Notifications + +The following requests are related to [email notifications](../user/profile/notifications.md) for issues. + +### Subscribe to an issue Subscribes the authenticated user to an issue to receive notifications. If the user is already subscribed to the issue, the status code `304` @@ -1620,13 +1672,19 @@ is returned. POST /projects/:id/issues/:issue_iid/subscribe ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe" ``` Example response: @@ -1751,9 +1809,9 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. -## Unsubscribe from an issue +### 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 @@ -1763,13 +1821,19 @@ status code `304` is returned. POST /projects/:id/issues/:issue_iid/unsubscribe ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe" ``` Example response: @@ -1837,13 +1901,19 @@ returned. POST /projects/:id/issues/:issue_iid/todo ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/todo" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/todo" ``` Example response: @@ -1960,14 +2030,16 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `body` | String | yes | The content of a note. Must contain `/promote` at the start of a new line. | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `body` | String | Yes | The content of a note. Must contain `/promote` at the start of a new line. If the note only contains `/promote`, promotes the issue, but doesn't add a comment. Otherwise, the other lines form a comment.| Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=Lets%20promote%20this%20to%20an%20epic%0A%0A%2Fpromote" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=Lets%20promote%20this%20to%20an%20epic%0A%0A%2Fpromote" ``` Example response: @@ -2000,7 +2072,11 @@ Example response: } ``` -## Set a time estimate for an issue +## Time tracking + +The following requests are related to [time tracking](../user/project/time_tracking.md) on issues. + +### Set a time estimate for an issue Sets an estimated time of work for this issue. @@ -2008,14 +2084,20 @@ Sets an estimated time of work for this issue. POST /projects/:id/issues/:issue_iid/time_estimate ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| -| `duration` | string | yes | The duration in human format. e.g: `3h30m` | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `duration` | string | Yes | The duration in human-readable format. For example: `3h30m`. | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m" ``` Example response: @@ -2029,7 +2111,7 @@ Example response: } ``` -## Reset the time estimate for an issue +### Reset the time estimate for an issue Resets the estimated time for this issue to 0 seconds. @@ -2037,13 +2119,19 @@ Resets the estimated time for this issue to 0 seconds. POST /projects/:id/issues/:issue_iid/reset_time_estimate ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate" ``` Example response: @@ -2057,23 +2145,29 @@ Example response: } ``` -## Add spent time for an issue +### Add spent time for an issue -Adds spent time for this issue +Adds spent time for this issue. ```plaintext POST /projects/:id/issues/:issue_iid/add_spent_time ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| -| `duration` | string | yes | The duration in human format. e.g: `3h30m` | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `summary` | string | no | A summary of how the time was spent | +| `duration` | string | Yes | The duration in human-readable format. For example: `3h30m` | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `summary` | string | No | A summary of how the time was spent. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h" ``` Example response: @@ -2087,7 +2181,7 @@ Example response: } ``` -## Reset spent time for an issue +### Reset spent time for an issue Resets the total spent time for this issue to 0 seconds. @@ -2095,13 +2189,19 @@ Resets the total spent time for this issue to 0 seconds. POST /projects/:id/issues/:issue_iid/reset_spent_time ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time" ``` Example response: @@ -2115,22 +2215,29 @@ Example response: } ``` -## Get time tracking stats +### Get time tracking stats -If the project is private or the issue is confidential, you need to provide credentials to authorize. +Gets time tracking stats for an issue in human-readable format (for example, `1h30m`) and in number of seconds. + +If the project is private or the issue is confidential, you must provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext GET /projects/:id/issues/:issue_iid/time_stats ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats" ``` Example response: @@ -2144,9 +2251,13 @@ Example response: } ``` -## List merge requests related to issue +## Merge requests + +The following requests are related to relationships between issues and merge requests. + +### List merge requests related to issue -Get all the merge requests that are related to the issue. +Gets all the merge requests that are related to the issue. If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). @@ -2155,13 +2266,18 @@ The preferred way to do this, is by using [personal access tokens](../user/profi GET /projects/:id/issues/:issue_iid/related_merge_requests ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests" ``` Example response: @@ -2304,9 +2420,9 @@ Example response: ] ``` -## List merge requests that close a particular issue on merge +### List merge requests that close a particular issue on merge -Get all merge requests that close a particular issue when merged. +Gets all merge requests that close a particular issue when merged. If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). @@ -2315,13 +2431,18 @@ The preferred way to do this, is by using [personal access tokens](../user/profi GET /projects/:id/issues/:issue_iid/closed_by ``` +Supported attributes: + | Attribute | Type | Required | Description | | ----------- | ---------------| -------- | ---------------------------------- | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by" ``` Example response: @@ -2383,7 +2504,9 @@ Example response: ] ``` -## Participants on issues +## List participants in an issue + +Lists users that are participants in the issue. If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). @@ -2392,13 +2515,18 @@ The preferred way to do this, is by using [personal access tokens](../user/profi GET /projects/:id/issues/:issue_iid/participants ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/participants" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + -url "https://gitlab.example.com/api/v4/projects/5/issues/93/participants" ``` Example response: @@ -2426,23 +2554,31 @@ Example response: ## Comments on issues -Comments are done via the [notes](notes.md) resource. +Interact with comments using the [Notes API](notes.md). ## Get user agent details Available only for administrators. +Gets the user agent string and IP of the user who created the issue. +Used for spam tracking. + ```plaintext GET /projects/:id/issues/:issue_iid/user_agent_detail ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/user_agent_detail" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/user_agent_detail" ``` Example response: @@ -2457,28 +2593,43 @@ Example response: ## List issue state events -To track which state was set, who did it, and when it happened, check out +To track which state was set, who did it, and when it happened, use [Resource state events API](resource_state_events.md#issues). -## Upload metric image +## Incidents -Available only for Incident issues. +The following requests are available only for [incidents](../operations/incident_management/incidents.md). + +### Upload metric image + +Available only for [incidents](../operations/incident_management/incidents.md). + +Uploads a screenshot of metric charts to show in the incident's **Metrics** tab. +When you upload an image, you can associate the image with text or a link to the original graph. +If you add a URL, you can access the original graph by selecting the hyperlink above the uploaded image. ```plaintext POST /projects/:id/issues/:issue_iid/metric_images ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `file` | file | yes | The image file to be uploaded | -| `url` | string | no | The URL to view more metric information | -| `url_text` | string | no | A description of the image or URL | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `file` | file | Yes | The image file to be uploaded. | +| `url` | string | No | The URL to view more metric information. | +| `url_text` | string | No | A description of the image or URL. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --form 'file=@/path/to/file.png' \ ---form 'url=http://example.com' --form 'url_text=Example website' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --form 'file=@/path/to/file.png' \ + --form 'url=http://example.com' \ + --form 'url_text=Example website' \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" ``` Example response: @@ -2494,21 +2645,28 @@ Example response: } ``` -## List metric images +### List metric images -Available only for Incident issues. +Available only for [incidents](../operations/incident_management/incidents.md). + +Lists screenshots of metric charts shown in the incident's **Metrics** tab. ```plaintext GET /projects/:id/issues/:issue_iid/metric_images ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + -url "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" ``` Example response: @@ -2532,24 +2690,34 @@ Example response: ] ``` -## Update metric image +### Update metric image + +Available only for [incidents](../operations/incident_management/incidents.md). -Available only for Incident issues. +Edits attributes of a screenshot of metric charts shown in the incident's **Metrics** tab. ```plaintext PUT /projects/:id/issues/:issue_iid/metric_images/:image_id ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `image_id` | integer | yes | The ID of the image | -| `url` | string | no | The URL to view more metric information | -| `url_text` | string | no | A description of the image or URL | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `image_id` | integer | Yes | The ID of the image. | +| `url` | string | No | The URL to view more metric information. | +| `url_text` | string | No | A description of the image or URL. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --request PUT --form 'url=http://example.com' --form 'url_text=Example website' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --request PUT \ + --form 'url=http://example.com' \ + --form 'url_text=Example website' \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" ``` Example response: @@ -2565,22 +2733,30 @@ Example response: } ``` -## Delete metric image +### Delete metric image + +Available only for [incidents](../operations/incident_management/incidents.md). -Available only for Incident issues. +Delete a screenshot of metric charts shown in the incident's **Metrics** tab. ```plaintext DELETE /projects/:id/issues/:issue_iid/metric_images/:image_id ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `image_id` | integer | yes | The ID of the image | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `image_id` | integer | Yes | The ID of the image. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --request DELETE \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" ``` Can return the following status codes: |