---
stage: Create
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 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.

## List all merge request draft notes

Gets a list of all draft notes for a single merge request.

```plaintext
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](rest/index.md#namespaced-path-encoding)
| `merge_request_iid` | integer             | yes        | The IID of a project merge request

```json
[{
  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
  }
}]
```

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "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.

```plaintext
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](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.

```json
{
  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
  }
}
```

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "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.

```plaintext
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.

```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
```

## Modify existing draft note

Modify a draft note for a given merge request.

```plaintext
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.

```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "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.

```plaintext
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](rest/index.md#namespaced-path-encoding).
| `merge_request_iid` | integer           | yes        | The IID of a project merge request.

```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "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.

```plaintext
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](rest/index.md#namespaced-path-encoding).
| `merge_request_iid` | integer           | yes        | The IID of a project merge request.

```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "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.

```plaintext
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](rest/index.md#namespaced-path-encoding).
| `merge_request_iid` | integer           | yes      | The IID of a project merge request.

```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/bulk_publish"
```