Draft Notes API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Draft notes are pending, unpublished comments on merge requests. They can either:
- Start a discussion.
- Continue an existing discussion as a reply.
Before publishing, draft notes are visible only to the author.
List all merge request draft notes
Gets a list of all draft notes for a single merge request.
GET /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 |
merge_request_iid | integer | yes | The IID of a project merge request |
[
{
"id": 5,
"author_id": 23,
"merge_request_id": 11,
"resolve_discussion": false,
"discussion_id": null,
"note": "Example title",
"commit_id": null,
"line_code": null,
"position": {
"base_sha": null,
"start_sha": null,
"head_sha": null,
"old_path": null,
"new_path": null,
"position_type": "text",
"old_line": null,
"new_line": null,
"line_range": null
}
}
]
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes"
Get a single draft note
Returns a single draft note for a given merge request.
GET /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. |
draft_note_id | integer | yes | The ID of a draft note. |
merge_request_iid | integer | yes | The IID of a project merge request. |
[
{
"id": 5,
"author_id": 23,
"merge_request_id": 11,
"resolve_discussion": false,
"discussion_id": null,
"note": "Example title",
"commit_id": null,
"line_code": null,
"position": {
"base_sha": null,
"start_sha": null,
"head_sha": null,
"old_path": null,
"new_path": null,
"position_type": "text",
"old_line": null,
"new_line": null,
"line_range": null
}
}
]
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5"
Create a draft note
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. |
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 , image , or file . file introduced in GitLab 16.4. |
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. |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes?note=note"
Modify existing draft note
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. |
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 , image or file . file introduced in GitLab 16.4. |
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. |
curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5"
Delete a draft note
Deletes an existing draft note for a given merge request.
DELETE /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id
Attribute | Type | Required | Description |
---|---|---|---|
draft_note_id | integer | yes | The ID of a draft note. |
id | integer or string | yes | The ID or URL-encoded path of the project. |
merge_request_iid | integer | yes | The IID of a project merge request. |
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5"
Publish a draft note
Publishes an existing draft note for a given merge request.
PUT /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id/publish
Attribute | Type | Required | Description |
---|---|---|---|
draft_note_id | integer | yes | The ID of a draft note. |
id | integer or string | yes | The ID or URL-encoded path of the project. |
merge_request_iid | integer | yes | The IID of a project merge request. |
curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5/publish"
Publish all pending draft notes
Bulk publishes all existing draft notes for a given merge request that belong to the user.
POST /projects/:id/merge_requests/:merge_request_iid/draft_notes/bulk_publish
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project. |
merge_request_iid | integer | yes | The IID of a project merge request. |
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/bulk_publish"
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support