Use this API to manage draft notes. These notes are pending, unpublished comments on merge requests. Draft notes can start a discussion, or continue an existing discussion as a reply.

Before publishing, draft notes are visible only to the author.

List all merge request draft notes

GET /api/v4/projects/{id}/merge_requests/{merge_request_iid}/draft_notes

Lists all merge request draft notes.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a project
merge_request_iid
Path, required		IntegerThe ID of a merge request

Responses

CodeDescriptionSchema
200OKAPIEntitiesDraftNote
400Bad Request—
401Unauthorized—
404Not found—

Create a draft note

POST /api/v4/projects/{id}/merge_requests/{merge_request_iid}/draft_notes

Creates a draft note for a specified merge request.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a project
merge_request_iid
Path, required		IntegerThe ID of a merge request

Request body (application/json)

PropertyTypeDescription
commit_idStringThe sha of a commit to associate the draft note to
in_reply_to_discussion_idStringThe ID of a discussion the draft note replies to
note
Required		StringThe content of a note
positionObjectPosition when creating a note
position.base_sha
Required		StringBase commit SHA in the source branch
position.head_sha
Required		StringSHA referencing HEAD of this merge request
position.heightIntegerHeight of the image
position.line_rangeObjectLine range for a multi-line note
position.line_range.endObjectEnd line for a multi-line note
position.line_range.end.line_codeStringEnd line code for multi-line note
position.line_range.end.new_lineIntegerEnd new_line line number
position.line_range.end.old_lineIntegerEnd old_line line number
position.line_range.end.typeStringEnd line type for multi-line note
position.line_range.startObjectStart line for a multi-line note
position.line_range.start.line_codeStringStart line code for multi-line note
position.line_range.start.new_lineIntegerStart new_line line number
position.line_range.start.old_lineIntegerStart old_line line number
position.line_range.start.typeStringStart line type for multi-line note
position.new_lineIntegerLine number after change
position.new_pathStringFile path after change
position.old_lineIntegerLine number before change
position.old_pathStringFile path before change
position.position_type
Required		StringType of the position reference
Allowed values: text, image, file
Minimum length: 1
position.start_sha
Required		StringSHA referencing commit in target branch
position.widthIntegerWidth of the image
position.xIntegerX coordinate in the image
position.yIntegerY coordinate in the image
resolve_discussionBooleanThe associated discussion should be resolved

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesDraftNote
400Bad Request—
401Unauthorized—
404Not found—

Publish all pending draft notes

POST /api/v4/projects/{id}/merge_requests/{merge_request_iid}/draft_notes/bulk_publish

Publishes all pending draft notes for the current user on the specified merge request. Optionally sets the reviewer state and posts a summary note.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a project
merge_request_iid
Path, required		IntegerThe ID of a merge request

Request body (application/json)

PropertyTypeDescription
internalBooleanIf true, the summary note is internal
Default: false
noteStringSummary note body to post on the merge request
reviewer_stateStringSet reviewer review state after publishing. Does not record a formal approval
Allowed values: requested_changes, reviewed

Responses

CodeDescriptionSchema
204No Content—
400Bad Request—
401Unauthorized—
404Not found—

Retrieve a draft note

GET /api/v4/projects/{id}/merge_requests/{merge_request_iid}/draft_notes/{draft_note_id}

Retrieves a draft note for a specified merge request.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a project
merge_request_iid
Path, required		IntegerThe ID of a merge request
draft_note_id
Path, required		IntegerThe ID of a draft note

Responses

CodeDescriptionSchema
200OKAPIEntitiesDraftNote
400Bad Request—
401Unauthorized—
404Not found—

Update a draft note

PUT /api/v4/projects/{id}/merge_requests/{merge_request_iid}/draft_notes/{draft_note_id}

Updates a draft note for a specified merge request.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a project
merge_request_iid
Path, required		IntegerThe ID of a merge request
draft_note_id
Path, required		IntegerThe ID of a draft note

Request body (application/json)

PropertyTypeDescription
noteStringThe content of a note
positionObjectPosition when creating a note
position.base_sha
Required		StringBase commit SHA in the source branch
position.head_sha
Required		StringSHA referencing HEAD of this merge request
position.heightIntegerHeight of the image
position.line_rangeObjectLine range for a multi-line note
position.line_range.endObjectEnd line for a multi-line note
position.line_range.end.line_codeStringEnd line code for multi-line note
position.line_range.end.new_lineIntegerEnd new_line line number
position.line_range.end.old_lineIntegerEnd old_line line number
position.line_range.end.typeStringEnd line type for multi-line note
position.line_range.startObjectStart line for a multi-line note
position.line_range.start.line_codeStringStart line code for multi-line note
position.line_range.start.new_lineIntegerStart new_line line number
position.line_range.start.old_lineIntegerStart old_line line number
position.line_range.start.typeStringStart line type for multi-line note
position.new_lineIntegerLine number after change
position.new_pathStringFile path after change
position.old_lineIntegerLine number before change
position.old_pathStringFile path before change
position.position_type
Required		StringType of the position reference
Allowed values: text, image, file
Minimum length: 1
position.start_sha
Required		StringSHA referencing commit in target branch
position.widthIntegerWidth of the image
position.xIntegerX coordinate in the image
position.yIntegerY coordinate in the image

Responses

CodeDescriptionSchema
200OKAPIEntitiesDraftNote
400Bad Request—
401Unauthorized—
404Not found—

Delete a draft note

DELETE /api/v4/projects/{id}/merge_requests/{merge_request_iid}/draft_notes/{draft_note_id}

Deletes a draft note for a specified merge request.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a project
merge_request_iid
Path, required		IntegerThe ID of a merge request
draft_note_id
Path, required		IntegerThe ID of a draft note

Responses

CodeDescriptionSchema
200OKAPIEntitiesDraftNote
400Bad Request—
401Unauthorized—
404Not found—

Publish a draft note

PUT /api/v4/projects/{id}/merge_requests/{merge_request_iid}/draft_notes/{draft_note_id}/publish

Publishes a draft note for a specified merge request.

Parameters

NameTypeDescription
id
Path, required		StringThe ID of a project
merge_request_iid
Path, required		IntegerThe ID of a merge request
draft_note_id
Path, required		IntegerThe ID of a draft note

Responses

CodeDescriptionSchema
204No Content—
400Bad Request—
401Unauthorized—
404Not found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesDraftNote

PropertyTypeDescription
author_idInteger (int64)Example: 4
commit_idStringExample: 6104942438c14ec7bd21c6cd5bd995272b3faff6
discussion_idStringExample: 6a9c1750b37d513a43987b574953fceb50b03ce7
idInteger (int64)Example: 2
line_codeStringExample: 1c497fbb3a46b78edf0_2_4
merge_request_idInteger (int64)Example: 52
noteStringExample: This is a note
positionObjectExample: {"base_sha":"aa149113","head_sha":"be3020c7","line_range":{"end":{"line_code":"1c497fbb3a46b78edf04cc2a2fa33f67e3ffbe2a_2_4","new_line":4,"old_line":2,"type":null},"start":{"line_code":"1c497fbb3a46b78edf04cc2a2fa33f67e3ffbe2a_2_4","new_line":4,"old_line":2,"type":null}},"new_line":4,"new_path":"example.md","old_line":2,"old_path":"example.md","position_type":"text","start_sha":"b3a0a8c4"}
resolve_discussionBooleanExample: true
←
REST API / Discussions
REST API / Environments
→