Draft Notes API

Tier: Free, Premium, Ultimate Offering: GitLab.com, 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: nil,
  note: "Example title",
  commit_id: nil,
  line_code: nil,
  position:
  {
    base_sha: nil,
    start_sha: nil,
    head_sha: nil,
    old_path: nil,
    new_path: nil,
    position_type: "text",
    old_line: nil,
    new_line: nil,
    line_range: nil
  }
}]

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: nil,
  note: "Example title",
  commit_id: nil,
  line_code: nil,
  position:
  {
    base_sha: nil,
    start_sha: nil,
    head_sha: nil,
    old_path: nil,
    new_path: nil,
    position_type: "text",
    old_line: nil,
    new_line: nil,
    line_range: nil
  }
}

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"