Add latest changes from gitlab-org/gitlab@16-0-stable-eev16.0.0-rc4216-0-stable

1 files changed, 238 insertions, 215 deletions

diff --git a/doc/api/discussions.md b/doc/api/discussions.md
index ccef57dab7f..15bbc802817 100644
--- a/doc/api/discussions.md
+++ b/doc/api/discussions.md
@@ -38,8 +38,8 @@ GET /projects/:id/issues/:issue_iid/discussions
 
 | Attribute           | Type             | Required   | Description  |
 | ------------------- | ---------------- | ---------- | ------------ |
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `issue_iid`         | integer          | yes        | The IID of an issue |
+| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `issue_iid`         | integer          | yes        | The IID of an issue. |
 
 ```json
 [
@@ -65,6 +65,7 @@ GET /projects/:id/issues/:issue_iid/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Issue",
+        "project_id": 5,
         "noteable_iid": null
       },
       {
@@ -85,6 +86,7 @@ GET /projects/:id/issues/:issue_iid/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Issue",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       }
@@ -112,6 +114,7 @@ GET /projects/:id/issues/:issue_iid/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Issue",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       }
@@ -127,7 +130,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>"\
 
 ### Get single issue discussion item
 
-Returns a single discussion item for a specific project issue
+Returns a single discussion item for a specific project issue.
 
 ```plaintext
 GET /projects/:id/issues/:issue_iid/discussions/:discussion_id
@@ -137,18 +140,18 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `issue_iid`     | integer        | yes      | The IID of an issue |
-| `discussion_id` | integer        | yes      | The ID of a discussion item |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `issue_iid`     | integer        | yes      | The IID of an issue. |
+| `discussion_id` | integer        | yes      | The ID of a discussion item. |
 
 ```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>"
 ```
 
 ### Create new issue thread
 
-Creates a new thread to a single project issue. This is similar to creating a note but other comments (replies) can be added to it later.
+Creates a new thread to a single project issue. Similar to creating a note, but other comments (replies) can be added to it later.
 
 ```plaintext
 POST /projects/:id/issues/:issue_iid/discussions
@@ -158,13 +161,13 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `issue_iid`     | integer        | yes      | The IID of an issue |
-| `body`          | string         | yes      | The content of the thread |
-| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
+| `body`          | string         | yes      | The content of the thread. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `issue_iid`     | integer        | yes      | The IID of an issue. |
+| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment"
 ```
 
@@ -172,7 +175,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
 
 Adds a new note to the thread. This can also [create a thread from a single comment](../user/discussions/index.md#create-a-thread-by-replying-to-a-standard-comment).
 
-**WARNING**
+WARNING:
 Notes can be added to other items than comments, such as system notes, making them threads.
 
 ```plaintext
@@ -183,15 +186,15 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `issue_iid`     | integer        | yes      | The IID of an issue |
-| `discussion_id` | integer        | yes      | The ID of a thread |
-| `note_id`       | integer        | yes      | The ID of a thread note |
-| `body`          | string         | yes      | The content of the note/reply |
-| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
+| `body`          | string         | yes      | The content of the note or reply. |
+| `discussion_id` | integer        | yes      | The ID of a thread. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `issue_iid`     | integer        | yes      | The IID of an issue. |
+| `note_id`       | integer        | yes      | The ID of a thread note. |
+| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights.
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>/notes?body=comment"
 ```
 
@@ -207,14 +210,14 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `issue_iid`     | integer        | yes      | The IID of an issue |
-| `discussion_id` | integer        | yes      | The ID of a thread |
-| `note_id`       | integer        | yes      | The ID of a thread note |
-| `body`          | string         | yes      | The content of the note/reply |
+| `body`          | string         | yes      | The content of the note or reply. |
+| `discussion_id` | integer        | yes      | The ID of a thread. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `issue_iid`     | integer        | yes      | The IID of an issue. |
+| `note_id`       | integer        | yes      | The ID of a thread note. |
 
 ```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/<discussion_id>/notes/1108?body=comment"
 ```
 
@@ -230,13 +233,13 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `issue_iid`     | integer        | yes      | The IID of an issue |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
+| `discussion_id` | integer        | yes      | The ID of a discussion. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `issue_iid`     | integer        | yes      | The IID of an issue. |
+| `note_id`       | integer        | yes      | The ID of a discussion note. |
 
 ```shell
-curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636"
 ```
 
@@ -252,8 +255,8 @@ GET /projects/:id/snippets/:snippet_id/discussions
 
 | Attribute           | Type             | Required   | Description |
 | ------------------- | ---------------- | ---------- | ------------|
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `snippet_id`        | integer          | yes        | The ID of an snippet |
+| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `snippet_id`        | integer          | yes        | The ID of an snippet. |
 
 ```json
 [
@@ -279,6 +282,7 @@ GET /projects/:id/snippets/:snippet_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Snippet",
+        "project_id": 5,
         "noteable_iid": null
       },
       {
@@ -299,6 +303,7 @@ GET /projects/:id/snippets/:snippet_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Snippet",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       }
@@ -326,6 +331,7 @@ GET /projects/:id/snippets/:snippet_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Snippet",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       }
@@ -335,13 +341,13 @@ GET /projects/:id/snippets/:snippet_id/discussions
 ```
 
 ```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions"
 ```
 
 ### Get single snippet discussion item
 
-Returns a single discussion item for a specific project snippet
+Returns a single discussion item for a specific project snippet.
 
 ```plaintext
 GET /projects/:id/snippets/:snippet_id/discussions/:discussion_id
@@ -351,19 +357,19 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `snippet_id`    | integer        | yes      | The ID of an snippet |
-| `discussion_id` | integer        | yes      | The ID of a discussion item |
+| `discussion_id` | integer        | yes      | The ID of a discussion item.
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `snippet_id`    | integer        | yes      | The ID of an snippet. |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>"
 ```
 
 ### Create new snippet thread
 
-Creates a new thread to a single project snippet. This is similar to creating
-a note but other comments (replies) can be added to it later.
+Creates a new thread to a single project snippet. Similar to creating
+a note, but other comments (replies) can be added to it later.
 
 ```plaintext
 POST /projects/:id/snippets/:snippet_id/discussions
@@ -373,10 +379,10 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `snippet_id`    | integer        | yes      | The ID of an snippet |
-| `body`          | string         | yes      | The content of a discussion |
-| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
+| `body`          | string         | yes      | The content of a discussion. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `snippet_id`    | integer        | yes      | The ID of an snippet. |
+| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
 
 ```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
@@ -395,15 +401,15 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `snippet_id`    | integer        | yes      | The ID of an snippet |
-| `discussion_id` | integer        | yes      | The ID of a thread |
-| `note_id`       | integer        | yes      | The ID of a thread note |
-| `body`          | string         | yes      | The content of the note/reply |
-| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
+| `body`          | string         | yes      | The content of the note or reply. |
+| `discussion_id` | integer        | yes      | The ID of a thread. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `note_id`       | integer        | yes      | The ID of a thread note. |
+| `snippet_id`    | integer        | yes      | The ID of an snippet. |
+| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>/notes?body=comment"
 ```
 
@@ -419,14 +425,14 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `snippet_id`    | integer        | yes      | The ID of an snippet |
-| `discussion_id` | integer        | yes      | The ID of a thread |
-| `note_id`       | integer        | yes      | The ID of a thread note |
-| `body`          | string         | yes      | The content of the note/reply |
+| `body`          | string         | yes      | The content of the note or reply. |
+| `discussion_id` | integer        | yes      | The ID of a thread. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `note_id`       | integer        | yes      | The ID of a thread note. |
+| `snippet_id`    | integer        | yes      | The ID of an snippet. |
 
 ```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/<discussion_id>/notes/1108?body=comment"
 ```
 
@@ -442,13 +448,13 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `snippet_id`    | integer        | yes      | The ID of an snippet |
-| `discussion_id` | integer        | yes      | The ID of a discussion |
-| `note_id`       | integer        | yes      | The ID of a discussion note |
+| `discussion_id` | integer        | yes      | The ID of a discussion. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `note_id`       | integer        | yes      | The ID of a discussion note. |
+| `snippet_id`    | integer        | yes      | The ID of an snippet. |
 
 ```shell
-curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636"
 ```
 
@@ -464,8 +470,8 @@ GET /groups/:id/epics/:epic_id/discussions
 
 | Attribute           | Type             | Required   | Description  |
 | ------------------- | ---------------- | ---------- | ------------ |
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
-| `epic_id`           | integer          | yes        | The ID of an epic |
+| `epic_id`           | integer          | yes        | The ID of an epic. |
+| `id`                | integer or string   | yes        | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
 
 ```json
 [
@@ -491,6 +497,7 @@ GET /groups/:id/epics/:epic_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Epic",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       },
@@ -512,6 +519,7 @@ GET /groups/:id/epics/:epic_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Epic",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       }
@@ -539,6 +547,7 @@ GET /groups/:id/epics/:epic_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Epic",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       }
@@ -554,7 +563,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>"\
 
 ### Get single epic discussion item
 
-Returns a single discussion item for a specific group epic
+Returns a single discussion item for a specific group epic.
 
 ```plaintext
 GET /groups/:id/epics/:epic_id/discussions/:discussion_id
@@ -564,19 +573,19 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
-| `epic_id`       | integer        | yes      | The ID of an epic |
-| `discussion_id` | integer        | yes      | The ID of a discussion item |
+| `discussion_id` | integer        | yes      | The ID of a discussion item. |
+| `epic_id`       | integer        | yes      | The ID of an epic. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>"
 ```
 
 ### Create new epic thread
 
-Creates a new thread to a single group epic. This is similar to creating
-a note but other comments (replies) can be added to it later.
+Creates a new thread to a single group epic. Similar to creating
+a note, but other comments (replies) can be added to it later.
 
 ```plaintext
 POST /groups/:id/epics/:epic_id/discussions
@@ -586,13 +595,13 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
-| `epic_id`       | integer        | yes      | The ID of an epic |
-| `body`          | string         | yes      | The content of the thread |
-| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
+| `body`          | string         | yes      | The content of the thread. |
+| `epic_id`       | integer        | yes      | The ID of an epic. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
+| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment"
 ```
 
@@ -609,15 +618,15 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
-| `epic_id`       | integer        | yes      | The ID of an epic |
-| `discussion_id` | integer        | yes      | The ID of a thread |
-| `note_id`       | integer        | yes      | The ID of a thread note |
-| `body`          | string         | yes      | The content of the note/reply |
-| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
+| `body`          | string         | yes      | The content of the note or reply. |
+| `discussion_id` | integer        | yes      | The ID of a thread. |
+| `epic_id`       | integer        | yes      | The ID of an epic. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
+| `note_id`       | integer        | yes      | The ID of a thread note. |
+| `created_at`    | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>/notes?body=comment"
 ```
 
@@ -633,14 +642,14 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
-| `epic_id`       | integer        | yes      | The ID of an epic |
-| `discussion_id` | integer        | yes      | The ID of a thread |
-| `note_id`       | integer        | yes      | The ID of a thread note |
-| `body`          | string         | yes      | The content of note/reply |
+| `body`          | string         | yes      | The content of note or reply. |
+| `discussion_id` | integer        | yes      | The ID of a thread. |
+| `epic_id`       | integer        | yes      | The ID of an epic. |
+| `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
+| `note_id`       | integer        | yes      | The ID of a thread note. |
 
 ```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/<discussion_id>/notes/1108?body=comment"
 ```
 
@@ -656,13 +665,13 @@ Parameters:
 
 | Attribute       | Type           | Required | Description |
 | --------------- | -------------- | -------- | ----------- |
-| `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
-| `epic_id`       | integer        | yes      | The ID of an epic |
-| `discussion_id` | integer        | yes      | The ID of a thread |
-| `note_id`       | integer        | yes      | The ID of a thread note |
+| `discussion_id` | integer        | yes      | The ID of a thread. |
+| `epic_id`       | integer        | yes      | The ID of an epic. |
+| `id`            | integer or string | yes      | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
+| `note_id`       | integer        | yes      | The ID of a thread note. |
 
 ```shell
-curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636"
 ```
 
@@ -678,8 +687,8 @@ GET /projects/:id/merge_requests/:merge_request_iid/discussions
 
 | Attribute           | Type             | Required   | Description  |
 | ------------------- | ---------------- | ---------- | ------------ |
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `merge_request_iid` | integer          | yes        | The IID of a merge request |
+| `id`                | integer or string   | yes        | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `merge_request_iid` | integer          | yes        | The IID of a merge request. |
 
 ```json
 [
@@ -705,6 +714,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Merge request",
+        "project_id": 5,
         "noteable_iid": null,
         "resolved": false,
         "resolvable": true,
@@ -729,6 +739,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Merge request",
+        "project_id": 5,
         "noteable_iid": null,
         "resolved": false,
         "resolvable": true,
@@ -758,6 +769,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Merge request",
+        "project_id": 5,
         "noteable_iid": null,
         "resolved": false,
         "resolvable": true,
@@ -794,6 +806,7 @@ Diff comments also contain position:
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Merge request",
+        "project_id": 5,
         "noteable_iid": null,
         "commit_id": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
         "position": {
@@ -826,13 +839,13 @@ Diff comments also contain position:
 ```
 
 ```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions"
 ```
 
 ### Get single merge request discussion item
 
-Returns a single discussion item for a specific project merge request
+Returns a single discussion item for a specific project merge request.
 
 ```plaintext
 GET /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id
@@ -842,12 +855,12 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a discussion item |
+| `discussion_id`     | string        | yes      | The ID of a discussion item. |
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `merge_request_iid` | integer        | yes      | The IID of a merge request. |
 
 ```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>"
 ```
 
@@ -855,8 +868,10 @@ curl --header "PRIVATE-TOKEN: <your_access_token>"\
 
 > The `commit id` entry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47130) in GitLab 13.7.
 
-Creates a new thread to a single project merge request. This is similar to creating
-a note but other comments (replies) can be added to it later.
+Creates a new thread to a single project merge request. Similar to creating
+a note but other comments (replies) can be added to it later. For other approaches,
+see [Post comment to commit](commits.md#post-comment-to-commit) in the Commits API,
+and [Create new merge request note](notes.md#create-new-merge-request-note) in the Notes API.
 
 ```plaintext
 POST /projects/:id/merge_requests/:merge_request_iid/discussions
@@ -866,30 +881,30 @@ Parameters for all comments:
 
 | Attribute                                | Type           | Required | Description |
 | ---------------------------------------- | -------------- | -------- | ----------- |
-| `id`                                     | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `merge_request_iid`                      | integer        | yes      | The IID of a merge request |
-| `body`                                   | string         | yes      | The content of the thread |
-| `commit_id`                              | string         | no       | SHA referencing commit to start this thread on |
-| `created_at`                             | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
-| `position`                               | hash           | no       | Position when creating a diff note |
-| `position[base_sha]`                     | string         | yes      | Base commit SHA in the source branch |
-| `position[start_sha]`                    | string         | yes      | SHA referencing commit in target branch |
-| `position[head_sha]`                     | string         | yes      | SHA referencing HEAD of this merge request |
-| `position[position_type]`                | string         | yes      | Type of the position reference', allowed values: `text` or `image` |
-| `position[new_path]`                     | string         | yes (if the position type is `text`) | File path after change |
-| `position[new_line]`                     | integer        | no       | Line number after change (for `text` diff notes) |
-| `position[old_path]`                     | string         | yes (if the position type is `text`) | File path before change |
-| `position[old_line]`                     | integer        | no       | Line number before change (for `text` diff notes) |
-| `position[line_range]`                   | hash           | no       | Line range for a multi-line diff note |
-| `position[width]`                        | integer        | no       | Width of the image (for `image` diff notes) |
-| `position[height]`                       | integer        | no       | Height of the image (for `image` diff notes) |
-| `position[x]`                            | float          | no       | X coordinate (for `image` diff notes) |
-| `position[y]`                            | float          | no       | Y coordinate (for `image` diff notes) |
+| `body`                                   | string         | yes      | The content of the thread. |
+| `id`                                     | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `merge_request_iid`                      | integer        | yes      | The IID of a merge request. |
+| `position[base_sha]`                     | string         | yes      | Base commit SHA in the source branch. |
+| `position[head_sha]`                     | string         | yes      | SHA referencing HEAD of this merge request. |
+| `position[start_sha]`                    | string         | yes      | SHA referencing commit in target branch. |
+| `position[new_path]`                     | string         | yes (if the position type is `text`) | File path after change. |
+| `position[old_path]`                     | string         | yes (if the position type is `text`) | File path before change. |
+| `position[position_type]`                | string         | yes      | Type of the position reference. Allowed values: `text` or `image`. |
+| `commit_id`                              | string         | no       | SHA referencing commit to start this thread on. |
+| `created_at`                             | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
+| `position`                               | hash           | no       | Position when creating a diff note. |
+| `position[new_line]`                     | integer        | no       | For `text` diff notes, the line number after change. |
+| `position[old_line]`                     | integer        | no       | For `text` diff notes, the line number before change. |
+| `position[line_range]`                   | hash           | no       | Line range for a multi-line diff note. |
+| `position[width]`                        | integer        | no       | For `image` diff notes, width of the image. |
+| `position[height]`                       | integer        | no       | For `image` diff notes, height of the image. |
+| `position[x]`                            | float          | no       | For `image` diff notes, X coordinate. |
+| `position[y]`                            | float          | no       | For `image` diff notes, Y coordinate. |
 
 #### Create a new thread on the overview page
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment"
 ```
 
@@ -903,18 +918,17 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
   use `position[old_line]` and don't include `position[new_line]`.
 - To create a thread on an unchanged line, include both `position[new_line]` and
   `position[old_line]` for the line. These positions might not be the same if earlier
-  changes in the file changed the line number. This is a bug that we plan to fix in
-  [GraphQL `createDiffNote` forces clients to compute redundant information (#325161)](https://gitlab.com/gitlab-org/gitlab/-/issues/325161).
-- If you specify incorrect `base`/`head`/`start` `SHA` parameters, you might run
-  into the following bug:
-  [Merge request comments receive "download" link instead of inline code (#296829)](https://gitlab.com/gitlab-org/gitlab/-/issues/296829).
+  changes in the file changed the line number. For the discussion about a fix, see
+  [issue 32516](https://gitlab.com/gitlab-org/gitlab/-/issues/325161).
+- If you specify incorrect `base`, `head`, `start`, or `SHA` parameters, you might run
+  into the bug described in [issue #296829)](https://gitlab.com/gitlab-org/gitlab/-/issues/296829).
 
 To create a new thread:
 
 1. [Get the latest merge request version](merge_requests.md#get-merge-request-diff-versions):
 
    ```shell
-   curl --header "PRIVATE-TOKEN: <your_access_token>"\
+   curl --header "PRIVATE-TOKEN: <your_access_token>" \
      "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions"
    ```
 
@@ -957,12 +971,12 @@ Parameters for multiline comments only:
 
 | Attribute                                | Type           | Required | Description |
 | ---------------------------------------- | -------------- | -------- | ----------- |
-| `position[line_range][start]`            | hash           | no       | Multiline note starting line |
-| `position[line_range][start][line_code]` | string         | yes      | [Line code](#line-code) for the start line |
-| `position[line_range][start][type]`      | string         | yes      | Use `new` for lines added by this commit, otherwise `old`. |
-| `position[line_range][end]`              | hash           | no       | Multiline note ending line |
-| `position[line_range][end][line_code]`   | string         | yes      | [Line code](#line-code) for the end line |
+| `position[line_range][end][line_code]`   | string         | yes      | [Line code](#line-code) for the end line. |
 | `position[line_range][end][type]`        | string         | yes      | Use `new` for lines added by this commit, otherwise `old`. |
+| `position[line_range][start][line_code]` | string         | yes      | [Line code](#line-code) for the start line. |
+| `position[line_range][start][type]`      | string         | yes      | Use `new` for lines added by this commit, otherwise `old`. |
+| `position[line_range][end]`              | hash           | no       | Multiline note ending line. |
+| `position[line_range][start]`            | hash           | no       | Multiline note starting line. |
 
 #### Line code
 
@@ -976,9 +990,9 @@ For example, if a commit (`<COMMIT_ID>`) deletes line 463 in the README, you can
 on the deletion by referencing line 463 in the *old* file:
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]"\
-  --form "note=Very clever to remove this unnecessary line!"\
-  --form "path=README" --form "line=463" --form "line_type=old"\
+curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]" \
+  --form "note=Very clever to remove this unnecessary line!" \
+  --form "path=README" --form "line=463" --form "line_type=old" \
   "https://gitlab.com/api/v4/projects/47/repository/commits/<COMMIT_ID>/comments"
 ```
 
@@ -986,9 +1000,9 @@ If a commit (`<COMMIT_ID>`) adds line 157 to `hello.rb`, you can comment on the
 addition by referencing line 157 in the *new* file:
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]"\
-  --form "note=This is brilliant!" --form "path=hello.rb"\
-  --form "line=157" --form "line_type=new"\
+curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]" \
+  --form "note=This is brilliant!" --form "path=hello.rb" \
+  --form "line=157" --form "line_type=new" \
   "https://gitlab.com/api/v4/projects/47/repository/commits/<COMMIT_ID>/comments"
 ```
 
@@ -1008,13 +1022,13 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a thread |
-| `resolved`          | boolean        | yes      | Resolve/unresolve the discussion |
+| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `discussion_id`     | string        | yes      | The ID of a thread. |
+| `merge_request_iid` | integer        | yes      | The IID of a merge request. |
+| `resolved`          | boolean        | yes      | Resolve or unresolve the discussion. |
 
 ```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>?resolved=true"
 ```
 
@@ -1031,15 +1045,15 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a thread |
-| `note_id`           | integer        | yes      | The ID of a thread note |
-| `body`              | string         | yes      | The content of the note/reply |
-| `created_at`        | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
+| `body`              | string         | yes      | The content of the note or reply. |
+| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `discussion_id`     | string        | yes      | The ID of a thread. |
+| `merge_request_iid` | integer        | yes      | The IID of a merge request. |
+| `note_id`           | integer        | yes      | The ID of a thread note. |
+| `created_at`        | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes?body=comment"
 ```
 
@@ -1055,22 +1069,22 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a thread |
-| `note_id`           | integer        | yes      | The ID of a thread note |
-| `body`              | string         | no       | The content of the note/reply (exactly one of `body` or `resolved` must be set |
-| `resolved`          | boolean        | no       | Resolve/unresolve the note (exactly one of `body` or `resolved` must be set |
+| `discussion_id`     | string        | yes      | The ID of a thread. |
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `merge_request_iid` | integer        | yes      | The IID of a merge request. |
+| `note_id`           | integer        | yes      | The ID of a thread note. |
+| `body`              | string         | no       | The content of the note or reply. Exactly one of `body` or `resolved` must be set. |
+| `resolved`          | boolean        | no       | Resolve or unresolve the note. Exactly one of `body` or `resolved` must be set. |
 
 ```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes/1108?body=comment"
 ```
 
 Resolving a note:
 
 ```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/<discussion_id>/notes/1108?resolved=true"
 ```
 
@@ -1086,13 +1100,13 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `merge_request_iid` | integer        | yes      | The IID of a merge request |
-| `discussion_id`     | integer        | yes      | The ID of a thread |
-| `note_id`           | integer        | yes      | The ID of a thread note |
+| `discussion_id`     | string        | yes      | The ID of a thread. |
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `merge_request_iid` | integer        | yes      | The IID of a merge request. |
+| `note_id`           | integer        | yes      | The ID of a thread note. |
 
 ```shell
-curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636"
 ```
 
@@ -1108,8 +1122,8 @@ GET /projects/:id/repository/commits/:commit_id/discussions
 
 | Attribute           | Type             | Required   | Description  |
 | ------------------- | ---------------- | ---------- | ------------ |
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `commit_id`         | string           | yes        | The SHA of a commit |
+| `commit_id`         | string           | yes        | The SHA of a commit. |
+| `id`                | integer or string   | yes        | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
 
 ```json
 [
@@ -1135,6 +1149,7 @@ GET /projects/:id/repository/commits/:commit_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Commit",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       },
@@ -1156,6 +1171,7 @@ GET /projects/:id/repository/commits/:commit_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Commit",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       }
@@ -1183,6 +1199,7 @@ GET /projects/:id/repository/commits/:commit_id/discussions
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Commit",
+        "project_id": 5,
         "noteable_iid": null,
         "resolvable": false
       }
@@ -1217,6 +1234,7 @@ Diff comments contain also position:
         "system": false,
         "noteable_id": 3,
         "noteable_type": "Commit",
+        "project_id": 5,
         "noteable_iid": null,
         "position": {
           "base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef",
@@ -1236,7 +1254,7 @@ Diff comments contain also position:
 ```
 
 ```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions"
 ```
 
@@ -1252,18 +1270,18 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `commit_id`         | string         | yes      | The SHA of a commit |
-| `discussion_id`     | string         | yes      | The ID of a discussion item |
+| `commit_id`         | string         | yes      | The SHA of a commit. |
+| `discussion_id`     | string         | yes      | The ID of a discussion item. |
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
 
 ```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>"
 ```
 
 ### Create new commit thread
 
-Creates a new thread to a single project commit. This is similar to creating
+Creates a new thread to a single project commit. Similar to creating
 a note but other comments (replies) can be added to it later.
 
 ```plaintext
@@ -1274,32 +1292,37 @@ Parameters:
 
 | Attribute                 | Type           | Required | Description |
 | ------------------------- | -------------- | -------- | ----------- |
-| `id`                      | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `commit_id`               | string         | yes      | The SHA of a commit |
-| `body`                    | string         | yes      | The content of the thread |
-| `created_at`              | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
-| `position`                | hash           | no       | Position when creating a diff note |
-| `position[base_sha]`      | string         | yes      | SHA of the parent commit|
-| `position[start_sha]`     | string         | yes      | SHA of the parent commit |
-| `position[head_sha]`      | string         | yes      | The SHA of this commit (same as `commit_id`) |
-| `position[position_type]` | string         | yes      | Type of the position reference', allowed values: `text` or `image` |
-| `position[new_path]`      | string         | no       | File path after change |
-| `position[new_line]`      | integer        | no       | Line number after change |
-| `position[old_path]`      | string         | no       | File path before change |
-| `position[old_line]`      | integer        | no       | Line number before change |
-| `position[width]`         | integer        | no       | Width of the image (for `image` diff notes) |
-| `position[height]`        | integer        | no       | Height of the image (for `image` diff notes) |
-| `position[x]`             | integer        | no       | X coordinate (for `image` diff notes) |
-| `position[y]`             | integer        | no       | Y coordinate (for `image` diff notes) |
+| `body`                    | string         | yes      | The content of the thread. |
+| `commit_id`               | string         | yes      | The SHA of a commit. |
+| `id`                      | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `position[base_sha]`      | string         | yes      | SHA of the parent commit. |
+| `position[head_sha]`      | string         | yes      | The SHA of this commit. Same as `commit_id`. |
+| `position[start_sha]`     | string         | yes      | SHA of the parent commit. |
+| `position[position_type]` | string         | yes      | Type of the position reference. Allowed values: `text` or `image`. |
+| `created_at`              | string         | no       | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
+| `position`                | hash           | no       | Position when creating a diff note. |
+
+| `position[new_path]`      | string         | no       | File path after change. |
+| `position[new_line]`      | integer        | no       | Line number after change. |
+| `position[old_path]`      | string         | no       | File path before change. |
+| `position[old_line]`      | integer        | no       | Line number before change. |
+| `position[height]`        | integer        | no       | For `image` diff notes, image height. |
+| `position[width]`         | integer        | no       | For `image` diff notes, image width. |
+| `position[x]`             | integer        | no       | For `image` diff notes, X coordinate. |
+| `position[y]`             | integer        | no       | For `image` diff notes, Y coordinate. |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions?body=comment"
 ```
 
 The rules for creating the API request are the same as when
-[creating a new thread in the merge request diff](#create-a-new-thread-in-the-merge-request-diff),
-with the exception of `base_sha`, `start_sha`, and `head_sha` attributes.
+[creating a new thread in the merge request diff](#create-a-new-thread-in-the-merge-request-diff).
+The exceptions:
+
+- `base_sha`
+- `head_sha`
+- `start_sha`
 
 ### Add note to existing commit thread
 
@@ -1313,15 +1336,15 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `commit_id`         | string         | yes      | The SHA of a commit |
-| `discussion_id`     | string         | yes      | The ID of a thread |
-| `note_id`           | integer        | yes      | The ID of a thread note |
-| `body`              | string         | yes      | The content of the note/reply |
-| `created_at`        | string         | no       | Date time string, ISO 8601 formatted, such `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
+| `body`              | string         | yes      | The content of the note or reply. |
+| `commit_id`         | string         | yes      | The SHA of a commit. |
+| `discussion_id`     | string         | yes      | The ID of a thread. |
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `note_id`           | integer        | yes      | The ID of a thread note. |
+| `created_at`        | string         | no       | Date time string, ISO 8601 formatted, such `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. |
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>/notes?body=comment
 ```
 
@@ -1337,21 +1360,21 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `commit_id`         | string         | yes      | The SHA of a commit |
-| `discussion_id`     | string         | yes      | The ID of a thread |
-| `note_id`           | integer        | yes      | The ID of a thread note |
-| `body`              | string         | no       | The content of a note |
+| `commit_id`         | string         | yes      | The SHA of a commit. |
+| `discussion_id`     | string         | yes      | The ID of a thread. |
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `note_id`           | integer        | yes      | The ID of a thread note. |
+| `body`              | string         | no       | The content of a note. |
 
 ```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>/notes/1108?body=comment"
 ```
 
 Resolving a note:
 
 ```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>/notes/1108?resolved=true"
 ```
 
@@ -1367,12 +1390,12 @@ Parameters:
 
 | Attribute           | Type           | Required | Description |
 | ------------------- | -------------- | -------- | ----------- |
-| `id`                | integer/string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) |
-| `commit_id`         | string         | yes      | The SHA of a commit |
-| `discussion_id`     | string         | yes      | The ID of a thread |
-| `note_id`           | integer        | yes      | The ID of a thread note |
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
+| `commit_id`         | string         | yes      | The SHA of a commit. |
+| `discussion_id`     | string         | yes      | The ID of a thread. |
+| `note_id`           | integer        | yes      | The ID of a thread note. |
 
 ```shell
-curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>"\
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
   "https://gitlab.example.com/api/v4/projects/5/repository/commits/<commit_id>/discussions/<discussion_id>/notes/636"
 ```