diff options
Diffstat (limited to 'doc/api/draft_notes.md')
| -rw-r--r-- | doc/api/draft_notes.md | 58 |
1 files changed, 43 insertions, 15 deletions
diff --git a/doc/api/draft_notes.md b/doc/api/draft_notes.md index e532de6a502..3f4ea46f00d 100644 --- a/doc/api/draft_notes.md +++ b/doc/api/draft_notes.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Draft Notes API **(FREE)** +# Draft Notes API **(FREE ALL)** Draft notes are pending, unpublished comments on merge requests. They can be either start a discussion, or be associated with an existing discussion as a reply. They are viewable only by the author until they are published. @@ -102,14 +102,28 @@ Create a draft note for a given merge request. POST /projects/:id/merge_requests/:merge_request_iid/draft_notes ``` -| Attribute | Type | Required | Description | -| --------------------------- | ----------------- | ----------- | --------------------- | -| `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 project merge request. -| `note` | string | yes | The content of a note. -| `commit_id` | string | no | The SHA of a commit to associate the draft note to. -| `in_reply_to_discussion_id` | integer | no | The ID of a discussion the draft note replies to. -| `resolve_discussion` | boolean | no | The associated discussion should be resolved. +| Attribute | Type | Required | Description | +| ---------------------------------------- | ----------------- | ----------- | --------------------- | +| `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 project merge request. +| `note` | string | yes | The content of a note. +| `commit_id` | string | no | The SHA of a commit to associate the draft note to. +| `in_reply_to_discussion_id` | string | no | The ID of a discussion the draft note replies to. +| `resolve_discussion` | boolean | no | The associated discussion should be resolved. +| `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`. | +| `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. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes?note=note @@ -123,12 +137,26 @@ Modify a draft note for a given merge request. PUT /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id ``` -| Attribute | Type | Required | Description | -| ------------------- | ----------------- | ----------- | --------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). -| `draft_note_id` | integer | yes | The ID of a draft note. -| `merge_request_iid` | integer | yes | The IID of a project merge request. -| `note` | string | no | The content of a note. +| Attribute | Type | Required | Description | +| ------------------- | ----------------- | ----------- | --------------------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `draft_note_id` | integer | yes | The ID of a draft note. +| `merge_request_iid` | integer | yes | The IID of a project merge request. +| `note` | string | no | The content of a note. +| `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`. | +| `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. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5" |