2020-10-28 11:08:49 -04:00
---
2020-11-17 10:09:28 -05:00
stage: Plan
group: Project Management
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-28 11:08:49 -04:00
---
2021-05-13 11:10:20 -04:00
# Notes API **(FREE)**
2014-05-27 08:12:15 -04:00
2019-05-29 19:25:19 -04:00
Notes are comments on:
- Snippets
- Issues
- Merge requests
2022-08-08 11:10:32 -04:00
- [Epics ](../user/group/epics/index.md )
2013-02-20 16:17:05 -05:00
2020-07-28 08:09:49 -04:00
This includes system notes, which are notes about changes to the object (for example, when an
2020-12-11 10:10:04 -05:00
assignee changes, GitLab posts a system note).
2020-07-28 08:09:49 -04:00
## Resource events
2020-09-11 11:08:30 -04:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38096) in GitLab 13.3 for state, milestone, and weight events.
2021-05-13 11:10:20 -04:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40850) in GitLab 13.4 for iteration events.
2020-07-28 08:09:49 -04:00
Some system notes are not part of this API, but are recorded as separate events:
- [Resource label events ](resource_label_events.md )
- [Resource state events ](resource_state_events.md )
- [Resource milestone events ](resource_milestone_events.md )
2021-05-13 11:10:20 -04:00
- [Resource weight events ](resource_weight_events.md )
- [Resource iteration events ](resource_iteration_events.md )
2019-04-16 12:31:23 -04:00
2019-04-15 19:35:20 -04:00
## Notes pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
2021-06-28 11:08:03 -04:00
Read more on [pagination ](index.md#pagination ).
2019-04-15 19:35:20 -04:00
2021-02-09 16:09:19 -05:00
## Rate limits
To help avoid abuse, you can limit your users to a specific number of `Create` request per minute.
See [Notes rate limits ](../user/admin_area/settings/rate_limit_on_notes_creation.md ).
2013-02-20 16:17:05 -05:00
## Issues
### List project issue notes
2015-12-25 11:13:55 -05:00
Gets a list of all notes for a single issue.
2012-11-29 15:32:05 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
GET /projects/:id/issues/:issue_iid/notes
2017-11-29 11:22:22 -05:00
GET /projects/:id/issues/:issue_iid/notes?sort=asc& order_by=updated_at
2012-11-29 15:32:05 -05:00
```
2017-11-29 11:22:22 -05:00
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding )
2017-11-29 11:22:22 -05:00
| `issue_iid` | integer | yes | The IID of an issue
| `sort` | string | no | Return issue notes sorted in `asc` or `desc` order. Default is `desc`
| `order_by` | string | no | Return issue notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
2012-11-29 15:32:05 -05:00
2013-10-02 06:08:07 -04:00
```json
[
{
2014-04-05 02:36:47 -04:00
"id": 302,
2016-11-23 01:55:23 -05:00
"body": "closed",
2014-04-05 02:36:47 -04:00
"attachment": null,
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
2013-10-02 06:08:07 -04:00
},
2015-08-12 15:39:58 -04:00
"created_at": "2013-10-02T09:22:45Z",
2016-04-12 06:32:34 -04:00
"updated_at": "2013-10-02T10:22:45Z",
2015-11-21 15:36:31 -05:00
"system": true,
2015-12-04 06:21:06 -05:00
"noteable_id": 377,
2017-08-08 07:31:55 -04:00
"noteable_type": "Issue",
2018-05-01 08:39:44 -04:00
"noteable_iid": 377,
2020-03-30 14:08:07 -04:00
"resolvable": false,
2022-08-15 08:11:43 -04:00
"confidential": false,
"internal": false
2013-10-02 06:08:07 -04:00
},
{
2014-04-05 02:36:47 -04:00
"id": 305,
"body": "Text of the comment\r\n",
"attachment": null,
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
2013-10-02 06:08:07 -04:00
},
2015-08-12 15:39:58 -04:00
"created_at": "2013-10-02T09:56:03Z",
2016-04-12 06:32:34 -04:00
"updated_at": "2013-10-02T09:56:03Z",
2015-11-21 15:36:31 -05:00
"system": true,
2015-12-04 06:21:06 -05:00
"noteable_id": 121,
2017-08-08 07:31:55 -04:00
"noteable_type": "Issue",
2018-05-01 08:39:44 -04:00
"noteable_iid": 121,
2020-03-30 14:08:07 -04:00
"resolvable": false,
2022-08-15 08:11:43 -04:00
"confidential": true,
"internal": true
2013-10-02 06:08:07 -04:00
}
]
```
2013-02-20 16:17:05 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
2018-02-28 02:48:23 -05:00
```
2013-02-20 16:17:05 -05:00
### Get single issue note
Returns a single note for a specific project issue
2012-11-29 15:32:05 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
GET /projects/:id/issues/:issue_iid/notes/:note_id
2012-11-29 15:32:05 -05:00
```
Parameters:
2021-11-22 13:10:55 -05:00
| Attribute | Type | Required | Description |
|-------------|----------------|----------|---------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
| `issue_iid` | integer | yes | The IID of a project issue |
| `note_id` | integer | yes | The ID of an issue note |
2012-11-29 15:32:05 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
2018-02-28 02:48:23 -05:00
```
2013-02-20 16:17:05 -05:00
### Create new issue note
2012-12-01 05:20:45 -05:00
2018-02-28 02:48:23 -05:00
Creates a new note to a single project issue.
2012-12-01 05:20:45 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
POST /projects/:id/issues/:issue_iid/notes
2012-12-01 05:20:45 -05:00
```
Parameters:
2021-11-22 13:10:55 -05:00
| Attribute | Type | Required | Description |
|----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
2022-04-08 17:09:52 -04:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ). |
| `issue_iid` | integer | yes | The IID of an issue. |
2021-11-22 13:10:55 -05:00
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
2022-08-15 08:11:43 -04:00
| `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0 and renamed to `internal` . The confidential flag of a note. Default is false. |
| `internal` | boolean | no | The internal flag of a note. Overrides `confidential` when both parameters are submitted. Default is false. |
2022-07-19 11:09:10 -04:00
| `created_at` | string | no | Date time string, ISO 8601 formatted. It must be after 1970-01-01. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
2013-02-20 16:17:05 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
2018-02-28 02:48:23 -05:00
```
2014-09-02 11:12:13 -04:00
### Modify existing issue note
Modify existing note of an issue.
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
PUT /projects/:id/issues/:issue_iid/notes/:note_id
2014-09-02 11:12:13 -04:00
```
Parameters:
2022-04-08 17:09:52 -04:00
| Attribute | Type | Required | Description |
|----------------|----------------|-------------|----------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ). |
| `issue_iid` | integer | yes | The IID of an issue. |
| `note_id` | integer | yes | The ID of a note. |
| `body` | string | no | The content of a note. Limited to 1,000,000 characters. |
| `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. |
2014-09-02 11:12:13 -04:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
2018-02-28 02:48:23 -05:00
```
2016-04-06 13:04:17 -04:00
### Delete an issue note
2016-04-05 19:21:02 -04:00
2016-11-24 12:28:52 -05:00
Deletes an existing note of an issue.
2016-04-05 19:21:02 -04:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
DELETE /projects/:id/issues/:issue_iid/notes/:note_id
2016-04-05 19:21:02 -04:00
```
Parameters:
2016-04-06 13:04:17 -04:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2017-03-27 09:01:45 -04:00
| `issue_iid` | integer | yes | The IID of an issue |
2016-04-06 13:04:17 -04:00
| `note_id` | integer | yes | The ID of a note |
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636"
2016-04-06 13:04:17 -04:00
```
2013-02-20 16:17:05 -05:00
## Snippets
2021-01-11 16:10:36 -05:00
The Snippets Notes API is intended for project-level snippets, and not for personal snippets.
2013-02-20 16:17:05 -05:00
### List all snippet notes
Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.
2012-11-29 15:32:05 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2013-02-20 16:17:05 -05:00
GET /projects/:id/snippets/:snippet_id/notes
2017-11-29 11:22:22 -05:00
GET /projects/:id/snippets/:snippet_id/notes?sort=asc& order_by=updated_at
2012-11-29 15:32:05 -05:00
```
2017-11-29 11:22:22 -05:00
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding )
2017-11-29 11:22:22 -05:00
| `snippet_id` | integer | yes | The ID of a project snippet
| `sort` | string | no | Return snippet notes sorted in `asc` or `desc` order. Default is `desc`
| `order_by` | string | no | Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
2012-11-29 15:32:05 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes"
2018-02-28 02:48:23 -05:00
```
2013-02-20 16:17:05 -05:00
### Get single snippet note
2012-11-29 15:32:05 -05:00
2013-02-20 16:17:05 -05:00
Returns a single note for a given snippet.
2012-11-29 15:32:05 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2013-02-20 16:17:05 -05:00
GET /projects/:id/snippets/:snippet_id/notes/:note_id
2012-11-29 15:32:05 -05:00
```
Parameters:
2021-11-22 13:10:55 -05:00
| Attribute | Type | Required | Description |
|--------------|----------------|----------|---------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
| `snippet_id` | integer | yes | The ID of a project snippet |
| `note_id` | integer | yes | The ID of a snippet note |
2012-11-29 15:32:05 -05:00
2013-10-02 06:08:07 -04:00
```json
{
2014-04-05 02:36:47 -04:00
"id": 52,
"title": "Snippet",
"file_name": "snippet.rb",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
2013-10-02 06:08:07 -04:00
},
2016-03-09 13:25:39 -05:00
"expires_at": null,
2014-04-05 02:36:47 -04:00
"updated_at": "2013-10-02T07:34:20Z",
"created_at": "2013-10-02T07:34:20Z"
2013-10-02 06:08:07 -04:00
}
```
2013-02-20 16:17:05 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11"
2018-02-28 02:48:23 -05:00
```
2013-02-20 16:17:05 -05:00
### Create new snippet note
2020-12-11 10:10:04 -05:00
Creates a new note for a single snippet. Snippet notes are user comments on snippets.
If you create a note where the body only contains an Award Emoji, GitLab returns this object.
2012-11-29 18:52:56 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2013-02-20 16:17:05 -05:00
POST /projects/:id/snippets/:snippet_id/notes
2012-11-29 18:52:56 -05:00
```
Parameters:
2021-11-22 13:10:55 -05:00
| Attribute | Type | Required | Description |
|--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
| `snippet_id` | integer | yes | The ID of a snippet |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
2014-09-02 11:12:13 -04:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note"
2018-02-28 02:48:23 -05:00
```
2014-09-02 11:12:13 -04:00
### Modify existing snippet note
Modify existing note of a snippet.
2020-02-27 04:09:01 -05:00
```plaintext
2014-09-02 11:12:13 -04:00
PUT /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
2021-11-22 13:10:55 -05:00
| Attribute | Type | Required | Description |
|--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a snippet note |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
2013-02-20 16:17:05 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note"
2018-02-28 02:48:23 -05:00
```
2016-04-06 13:04:17 -04:00
### Delete a snippet note
2016-04-05 19:21:02 -04:00
2016-11-24 12:28:52 -05:00
Deletes an existing note of a snippet.
2016-04-05 19:21:02 -04:00
2020-02-27 04:09:01 -05:00
```plaintext
2016-04-05 19:21:02 -04:00
DELETE /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
2016-04-06 13:04:17 -04:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2016-04-06 13:04:17 -04:00
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a note |
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659"
2016-04-06 13:04:17 -04:00
```
2022-01-25 07:14:14 -05:00
## Merge requests
2013-02-20 16:17:05 -05:00
### List all merge request notes
Gets a list of all notes for a single merge request.
2012-11-29 15:32:05 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
GET /projects/:id/merge_requests/:merge_request_iid/notes
2017-11-29 11:22:22 -05:00
GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc& order_by=updated_at
2012-11-29 15:32:05 -05:00
```
2017-11-29 11:22:22 -05:00
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding )
2017-11-29 11:22:22 -05:00
| `merge_request_iid` | integer | yes | The IID of a project merge request
| `sort` | string | no | Return merge request notes sorted in `asc` or `desc` order. Default is `desc`
| `order_by` | string | no | Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
2012-11-29 15:32:05 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes"
2018-02-28 02:48:23 -05:00
```
2013-02-20 16:17:05 -05:00
### Get single merge request note
Returns a single note for a given merge request.
2012-11-29 15:32:05 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
2012-11-29 15:32:05 -05:00
```
Parameters:
2021-11-22 13:10:55 -05:00
| Attribute | Type | Required | Description |
|---------------------|----------------|----------|---------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
| `merge_request_iid` | integer | yes | The IID of a project merge request |
| `note_id` | integer | yes | The ID of a merge request note |
2013-02-20 16:17:05 -05:00
2013-10-02 06:08:07 -04:00
```json
{
2014-04-05 02:36:47 -04:00
"id": 301,
"body": "Comment for MR",
"attachment": null,
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
2013-10-02 06:08:07 -04:00
},
2015-12-04 06:21:06 -05:00
"created_at": "2013-10-02T08:57:14Z",
2016-04-12 06:32:34 -04:00
"updated_at": "2013-10-02T08:57:14Z",
2015-12-04 06:21:06 -05:00
"system": false,
"noteable_id": 2,
2017-08-08 07:31:55 -04:00
"noteable_type": "MergeRequest",
2018-05-01 08:39:44 -04:00
"noteable_iid": 2,
2020-03-30 14:08:07 -04:00
"resolvable": false,
2022-08-15 08:11:43 -04:00
"confidential": false,
"internal": false
2013-10-02 06:08:07 -04:00
}
```
2013-02-20 16:17:05 -05:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1"
2018-02-28 02:48:23 -05:00
```
2013-02-20 16:17:05 -05:00
### Create new merge request note
Creates a new note for a single merge request.
2020-12-11 10:10:04 -05:00
If you create a note where the body only contains an Award Emoji, GitLab returns this object.
2013-02-20 16:17:05 -05:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
POST /projects/:id/merge_requests/:merge_request_iid/notes
2013-02-20 16:17:05 -05:00
```
Parameters:
2021-11-22 13:10:55 -05:00
| Attribute | Type | Required | Description |
|---------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
2022-03-15 05:07:33 -04:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
| `merge_request_iid` | integer | yes | The IID of a project merge request |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
2022-03-29 08:08:03 -04:00
| `merge_request_diff_sha` | string | no | Required for the `/merge` [quick action ](../user/project/quick_actions.md ). The SHA of the head commit, which ensures the merge request wasn't updated after the API request was sent. |
2014-09-02 11:12:13 -04:00
### Modify existing merge request note
Modify existing note of a merge request.
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
2014-09-02 11:12:13 -04:00
```
Parameters:
2022-04-08 17:09:52 -04:00
| Attribute | Type | Required | Description |
|---------------------|-------------------|----------|----------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
| `merge_request_iid` | integer | yes | The IID of a project merge request |
| `note_id` | integer | no | The ID of a note |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. |
2016-04-05 19:21:02 -04:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note"
2018-02-28 02:48:23 -05:00
```
2016-04-06 13:04:17 -04:00
### Delete a merge request note
2016-04-05 19:21:02 -04:00
2016-11-24 12:28:52 -05:00
Deletes an existing note of a merge request.
2016-04-05 19:21:02 -04:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-03-27 09:01:45 -04:00
DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
2016-04-05 19:21:02 -04:00
```
Parameters:
2016-04-06 13:04:17 -04:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2017-03-27 09:01:45 -04:00
| `merge_request_iid` | integer | yes | The IID of a merge request |
2016-04-06 13:04:17 -04:00
| `note_id` | integer | yes | The ID of a note |
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602"
2016-04-06 13:04:17 -04:00
```
2019-05-29 19:25:19 -04:00
2022-08-08 11:10:32 -04:00
## Epics **(PREMIUM)**
2019-05-29 19:25:19 -04:00
### List all epic notes
Gets a list of all notes for a single epic. Epic notes are comments users can post to an epic.
2022-04-12 17:10:16 -04:00
NOTE:
The epics notes API uses the epic ID instead of epic IID. If you use the epic's IID, GitLab returns either a 404
error or notes for the wrong epic. It's different from the [issue notes API ](#issues ) and
[merge requests notes API ](#merge-requests ).
2020-02-27 04:09:01 -05:00
```plaintext
2019-05-29 19:25:19 -04:00
GET /groups/:id/epics/:epic_id/notes
GET /groups/:id/epics/:epic_id/notes?sort=asc& order_by=updated_at
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ----------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the group ](index.md#namespaced-path-encoding ) |
2019-05-29 19:25:19 -04:00
| `epic_id` | integer | yes | The ID of a group epic |
| `sort` | string | no | Return epic notes sorted in `asc` or `desc` order. Default is `desc` |
| `order_by` | string | no | Return epic notes ordered by `created_at` or `updated_at` fields. Default is `created_at` |
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/5/epics/11/notes"
2019-05-29 19:25:19 -04:00
```
### Get single epic note
Returns a single note for a given epic.
2020-02-27 04:09:01 -05:00
```plaintext
2019-05-29 19:25:19 -04:00
GET /groups/:id/epics/:epic_id/notes/:note_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the group ](index.md#namespaced-path-encoding ) |
2019-05-29 19:25:19 -04:00
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
```json
{
"id": 52,
"title": "Epic",
"file_name": "epic.rb",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"expires_at": null,
"updated_at": "2013-10-02T07:34:20Z",
2020-03-30 14:08:07 -04:00
"created_at": "2013-10-02T07:34:20Z",
2022-08-15 08:11:43 -04:00
"confidential": false,
"internal": false
2019-05-29 19:25:19 -04:00
}
```
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1"
2019-05-29 19:25:19 -04:00
```
### Create new epic note
Creates a new note for a single epic. Epic notes are comments users can post to an epic.
2020-12-11 10:10:04 -05:00
If you create a note where the body only contains an Award Emoji, GitLab returns this object.
2019-05-29 19:25:19 -04:00
2020-02-27 04:09:01 -05:00
```plaintext
2019-05-29 19:25:19 -04:00
POST /groups/:id/epics/:epic_id/notes
```
Parameters:
2022-04-08 17:09:52 -04:00
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `epic_id` | integer | yes | The ID of an epic |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group ](index.md#namespaced-path-encoding ) |
2022-08-15 08:11:43 -04:00
| `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0 and is renamed to `internal` . The confidential flag of a note. Default is `false` . |
| `internal` | boolean | no | The internal flag of a note. Overrides `confidential` when both parameters are submitted. Default is `false` . |
2019-05-29 19:25:19 -04:00
2020-01-30 10:09:15 -05:00
```shell
2021-05-04 17:10:01 -04:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note"
2019-05-29 19:25:19 -04:00
```
### Modify existing epic note
Modify existing note of an epic.
2020-02-27 04:09:01 -05:00
```plaintext
2019-05-29 19:25:19 -04:00
PUT /groups/:id/epics/:epic_id/notes/:note_id
```
Parameters:
2022-04-08 17:09:52 -04:00
| Attribute | Type | Required | Description |
| ---------------| ----------------- | -------- | ---------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group ](index.md#namespaced-path-encoding ) |
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. |
2019-05-29 19:25:19 -04:00
2020-01-30 10:09:15 -05:00
```shell
2021-05-04 17:10:01 -04:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note"
2019-05-29 19:25:19 -04:00
```
### Delete an epic note
Deletes an existing note of an epic.
2020-02-27 04:09:01 -05:00
```plaintext
2019-05-29 19:25:19 -04:00
DELETE /groups/:id/epics/:epic_id/notes/:note_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
2021-11-22 13:10:55 -05:00
| `id` | integer or string | yes | The ID or [URL-encoded path of the group ](index.md#namespaced-path-encoding ) |
2019-05-29 19:25:19 -04:00
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/5/epics/52/notes/1659"
2019-05-29 19:25:19 -04:00
```