summaryrefslogtreecommitdiff
path: root/doc/api/issues.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/issues.md')
-rw-r--r--doc/api/issues.md176
1 files changed, 151 insertions, 25 deletions
diff --git a/doc/api/issues.md b/doc/api/issues.md
index ad5990f4a37..f6bab9ce676 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/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Issues API
@@ -16,11 +16,11 @@ are paginated.
Read more on [pagination](README.md#pagination).
-DANGER: **Deprecated:**
+WARNING:
The `reference` attribute in responses is deprecated in favor of `references`.
Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354).
-NOTE: **Note:**
+NOTE:
The `references.relative` attribute is relative to the group or project of the issue being requested.
When an issue is fetched from its project, the `relative` format is the same as the `short` format,
and when requested across groups or projects it's expected to be the same as the `full` format.
@@ -197,11 +197,11 @@ the `health_status` parameter:
]
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform
to the GitLab EE API.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042).
This value is only present for issues closed after GitLab 10.6 and if the user account
that closed the issue still exists.
@@ -375,10 +375,10 @@ the `health_status` parameter:
]
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042).
This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
@@ -558,10 +558,10 @@ the `health_status` parameter:
]
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
@@ -678,6 +678,7 @@ Example response:
},
"subscribed": true,
"moved_to_id": null,
+ "service_desk_reply_to": "service.desk@gitlab.com",
"epic_iid": null,
"epic": null
}
@@ -715,15 +716,15 @@ the `epic` property:
}
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform
to the GitLab EE API.
-DANGER: **Deprecated:**
+WARNING:
The `epic_iid` attribute is deprecated, and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042).
This value is only present for issues closed after GitLab 10.6 and if the user account
that closed the issue still exists.
@@ -877,14 +878,14 @@ property:
]
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-DANGER: **Deprecated:**
+WARNING:
The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157).
Please use `iid` of the `epic` attribute instead.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
@@ -1005,10 +1006,10 @@ the `health_status` parameter:
]
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
@@ -1158,11 +1159,11 @@ the `health_status` parameter:
]
```
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
-DANGER: **Deprecated:**
+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
@@ -1323,10 +1324,10 @@ the `health_status` parameter:
]
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
@@ -1432,10 +1433,10 @@ the `weight` parameter:
}
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
@@ -1622,13 +1623,68 @@ Example response:
}
```
-DANGER: **Deprecated:**
+WARNING:
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-NOTE: **Note:**
+NOTE:
The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed
the issue still exists.
+## Promote an issue to an epic **(PREMIUM)**
+
+Promotes an issue to an epic by adding a comment with the `/promote`
+[quick action](../user/project/quick_actions.md).
+
+To learn more about promoting issues to epics, visit [Manage epics](../user/group/epics/manage_epics.md#promote-an-issue-to-an-epic).
+
+```plaintext
+POST /projects/:id/issues/:issue_iid/notes
+```
+
+Supported attributes:
+
+| Attribute | Type | Required | Description |
+| :---------- | :------------- | :------- | :---------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.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. |
+
+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"
+```
+
+Example response:
+
+```json
+{
+ "id":699,
+ "type":null,
+ "body":"Lets promote this to an epic",
+ "attachment":null,
+ "author": {
+ "id":1,
+ "name":"Alexandra Bashirian",
+ "username":"eileen.lowe",
+ "state":"active",
+ "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+ "web_url":"https://gitlab.example.com/eileen.lowe"
+ },
+ "created_at":"2020-12-03T12:27:17.844Z",
+ "updated_at":"2020-12-03T12:27:17.844Z",
+ "system":false,
+ "noteable_id":461,
+ "noteable_type":"Issue",
+ "resolvable":false,
+ "confidential":false,
+ "noteable_iid":33,
+ "commands_changes": {
+ "promote_to_epic":true
+ }
+}
+```
+
## Set a time estimate for an issue
Sets an estimated time of work for this issue.
@@ -2085,3 +2141,73 @@ Example response:
To track which state was set, who did it, and when it happened, check out
[Resource state events API](resource_state_events.md#issues).
+
+## Upload metric image
+
+Available only for Incident issues.
+
+```plaintext
+POST /projects/:id/issues/:issue_iid/metric_images
+```
+
+| Attribute | Type | Required | Description |
+|-------------|---------|----------|--------------------------------------|
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.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 |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" --form 'file=@/path/to/file.png' \
+--form 'url=http://example.com' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images"
+```
+
+Example response:
+
+```json
+{
+ "id": 23,
+ "created_at": "2020-11-13T00:06:18.084Z",
+ "filename": "file.png",
+ "file_path": "/uploads/-/system/issuable_metric_image/file/23/file.png",
+ "url": "http://example.com"
+}
+```
+
+## List metric images
+
+Available only for Incident issues.
+
+```plaintext
+GET /projects/:id/issues/:issue_iid/metric_images
+```
+
+| Attribute | Type | Required | Description |
+|-------------|---------|----------|--------------------------------------|
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `issue_iid` | integer | yes | The internal ID of a project's issue |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images"
+```
+
+Example response:
+
+```json
+[
+ {
+ "id": 17,
+ "created_at": "2020-11-12T20:07:58.156Z",
+ "filename": "sample_2054",
+ "file_path": "/uploads/-/system/issuable_metric_image/file/17/sample_2054.png",
+ "url": "example.com/metric"
+ },
+ {
+ "id": 18,
+ "created_at": "2020-11-12T20:14:26.441Z",
+ "filename": "sample_2054",
+ "file_path": "/uploads/-/system/issuable_metric_image/file/18/sample_2054.png",
+ "url": "example.com/metric"
+ }
+]
+```