Merge branch 'jh-promote-issue-to-epic' into 'master'

Add a section on promoting issue to epic with the API

See merge request gitlab-org/gitlab!49123

doc/api/issues.md

@@ -1630,6 +1630,61 @@ 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.