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		StringID or URL-encoded path of the project
merge_request_iid
Path, required		IntegerInternal ID of the merge request

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesDraftNote
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		StringID or URL-encoded path of the project
merge_request_iid
Path, required		IntegerInternal ID of the merge request

Request body (application/json)

PropertyTypeDescription
commit_idStringSHA of the commit to associate the draft note with
in_reply_to_discussion_idStringID of the discussion the draft note replies to
note
Required		StringContent of the note
positionObjectPosition when creating a diff note. If omitted, creates a regular discussion note
position.base_sha
Required		StringBase commit SHA of the diff
position.head_sha
Required		StringSHA of the latest commit in the source branch
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 a multi-line note
position.line_range.end.new_lineIntegerLine number after the change at the end of the line range
position.line_range.end.old_lineIntegerLine number before the change at the end of the line range
position.line_range.end.typeStringEnd line type for a multi-line note
position.line_range.startObjectStart line for a multi-line note
position.line_range.start.line_codeStringStart line code for a multi-line note
position.line_range.start.new_lineIntegerLine number after the change at the start of the line range
position.line_range.start.old_lineIntegerLine number before the change at the start of the line range
position.line_range.start.typeStringStart line type for a multi-line note
position.new_lineIntegerLine number after the change
position.new_pathStringFile path after the change
position.old_lineIntegerLine number before the change
position.old_pathStringFile path before the change
position.position_type
Required		StringType of the position reference
Allowed values: text, image, file
Minimum length: 1
position.start_sha
Required		StringSHA of the latest commit in the target branch
position.widthIntegerWidth of the image
position.xIntegerX coordinate in the image
position.yIntegerY coordinate in the image
resolve_discussionBooleanIf true, resolves the associated discussion

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		StringID or URL-encoded path of the project
merge_request_iid
Path, required		IntegerInternal ID of the merge request

Request body (application/json)

PropertyTypeDescription
internalBooleanIf true, the summary note is internal
Default: false
noteStringText of the summary note to add to the merge request
reviewer_stateStringSets the 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		StringID or URL-encoded path of the project
merge_request_iid
Path, required		IntegerInternal ID of the merge request
draft_note_id
Path, required		IntegerID of the 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		StringID or URL-encoded path of the project
merge_request_iid
Path, required		IntegerInternal ID of the merge request
draft_note_id
Path, required		IntegerID of the draft note

Request body (application/json)

PropertyTypeDescription
noteStringContent of the note
positionObjectPosition when creating a diff note. If omitted, creates a regular discussion note
position.base_sha
Required		StringBase commit SHA of the diff
position.head_sha
Required		StringSHA of the latest commit in the source branch
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 a multi-line note
position.line_range.end.new_lineIntegerLine number after the change at the end of the line range
position.line_range.end.old_lineIntegerLine number before the change at the end of the line range
position.line_range.end.typeStringEnd line type for a multi-line note
position.line_range.startObjectStart line for a multi-line note
position.line_range.start.line_codeStringStart line code for a multi-line note
position.line_range.start.new_lineIntegerLine number after the change at the start of the line range
position.line_range.start.old_lineIntegerLine number before the change at the start of the line range
position.line_range.start.typeStringStart line type for a multi-line note
position.new_lineIntegerLine number after the change
position.new_pathStringFile path after the change
position.old_lineIntegerLine number before the change
position.old_pathStringFile path before the change
position.position_type
Required		StringType of the position reference
Allowed values: text, image, file
Minimum length: 1
position.start_sha
Required		StringSHA of the latest commit in the 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		StringID or URL-encoded path of the project
merge_request_iid
Path, required		IntegerInternal ID of the merge request
draft_note_id
Path, required		IntegerID of the 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		StringID or URL-encoded path of the project
merge_request_iid
Path, required		IntegerInternal ID of the merge request
draft_note_id
Path, required		IntegerID of the 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
→