Notes API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
The Notes API manages comments and system records attached to GitLab content. The Notes API:
- Creates and modifies comments on issues, merge requests, epics, snippets, and commits.
- Retrieves system-generated notes about object changes.
- Provides options for sorting and pagination.
- Controls visibility through confidential and internal flags.
- Supports rate limiting to prevent abuse.
Some system-generated notes are tracked as separate resource events:
- Resource label events
- Resource state events
- Resource milestone events
- Resource weight events
- Resource iteration events
By default, GET requests return 20 results at a time, because the API results are paginated.
For more information, see Pagination.
Resource events
Some system notes are not part of this API, but are recorded as separate events:
- Resource label events
- Resource state events
- Resource milestone events
- Resource weight events
- Resource iteration events
Notes pagination
By default, GET requests return 20 results at a time because the API results
are paginated.
Read more on pagination.
Rate limits
To help avoid abuse, you can limit your users to a specific number of Create request per minute.
See Notes rate limits.
Issues
List project issue notes
Gets a list of all notes for a single issue.
GET /projects/:id/issues/:issue_iid/notes
GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer or string | yes | The ID or URL-encoded path of the project |
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
|
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"Get single issue note
Returns a single note for a specific project issue
GET /projects/:id/issues/:issue_iid/notes/:note_idParameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer or string | yes | The ID or URL-encoded path of the project |
issue_iid |
integer | yes | The IID of a project issue |
note_id |
integer | yes | The ID of an issue note |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"Create new issue note
Creates a new note to a single project issue.
POST /projects/:id/issues/:issue_iid/notesParameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer or string | yes | The ID or URL-encoded path of the project. |
issue_iid |
integer | yes | The IID of an issue. |
body |
string | yes | The content of a note. Limited to 1,000,000 characters. |
confidential |
boolean | no |
Deprecated: Scheduled to 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. |
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) |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"Modify existing issue note
Modify existing note of an issue.
PUT /projects/:id/issues/:issue_iid/notes/:note_idParameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer or string | yes | The ID or URL-encoded path of the project. |
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: Scheduled to be removed in GitLab 16.0. The confidential flag of a note. Default is false. |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636?body=note"Delete an issue note
Deletes an existing note of an issue.
DELETE /projects/:id/issues/:issue_iid/notes/:note_idParameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer or string | yes | The ID or URL-encoded path of the project |
issue_iid |
integer | yes | The IID of an issue |
note_id |
integer | yes | The ID of a note |
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```0
## Snippets
The Snippets Notes API is intended for project-level snippets, and not for personal snippets.
### List all snippet notes
Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```1
| Attribute | Type | Required | Description |
|--------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `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` |
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```2
### Get single snippet note
Returns a single note for a given snippet.
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```3
Parameters:
| Attribute | Type | Required | Description |
|--------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `snippet_id` | integer | yes | The ID of a project snippet |
| `note_id` | integer | yes | The ID of a snippet note |
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```4
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```5
### Create new snippet note
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 emoji reaction, GitLab returns this object.
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```6
Parameters:
| Attribute | Type | Required | Description |
|--------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `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) |
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```7
### Modify existing snippet note
Modify existing note of a snippet.
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```8
Parameters:
| Attribute | Type | Required | Description |
|--------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `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. |
```json
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
```9
### Delete a snippet note
Deletes an existing note of a snippet.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```0
Parameters:
| Attribute | Type | Required | Description |
|--------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a note |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```1
## Merge requests
### List all merge request notes
Gets a list of all notes for a single merge request.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```2
| Attribute | Type | Required | Description |
|---------------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `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` |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```3
### Get single merge request note
Returns a single note for a given merge request.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```4
Parameters:
| Attribute | Type | Required | Description |
|---------------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `merge_request_iid` | integer | yes | The IID of a project merge request |
| `note_id` | integer | yes | The ID of a merge request note |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```5
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```6
### Create new merge request note
Creates a new note for a single merge request. Notes are not attached to specific
lines in a merge request. For other approaches with more granular control, see
[Post comment to commit](commits.md#post-comment-to-commit) in the Commits API,
and [Create a new thread in the merge request diff](discussions.md#create-a-new-thread-in-the-merge-request-diff)
in the Discussions API.
If you create a note where the body only contains an emoji reaction, GitLab returns this object.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```7
Parameters:
| Attribute | Type | Required | Description |
|-------------------------------|-------------------|----------|-------------|
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `merge_request_iid` | integer | yes | The IID of a project merge request |
| `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
| `internal` | boolean | no | The internal flag of a note. Default is false. |
| `merge_request_diff_head_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. |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```8
### Modify existing merge request note
Modify existing note of a merge request.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
```9
Parameters:
| Attribute | Type | Required | Description |
|---------------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `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:** Scheduled to be removed in GitLab 16.0. The confidential flag of a note. Default is false. |
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```0
### Delete a merge request note
Deletes an existing note of a merge request.
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```1
Parameters:
| Attribute | Type | Required | Description |
|---------------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
| `note_id` | integer | yes | The ID of a note |
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```2
## Epics
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if [the new look for epics](../user/group/epics/epic_work_items.md) is enabled, use the
Work Items API instead. For more information, see [migrate epic APIs to work items](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
### List all epic notes
Gets a list of all notes for a single epic. Epic notes are comments users can post to an epic.
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).
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```3
| Attribute | Type | Required | Description |
|------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
| `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` |
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```4
### Get single epic note
Returns a single note for a given epic.
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```5
Parameters:
| Attribute | Type | Required | Description |
|-----------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```6
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```7
### Create new epic note
Creates a new note for a single epic. Epic notes are comments users can post to an epic.
If you create a note where the body only contains an emoji reaction, GitLab returns this object.
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```8
Parameters:
| 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](rest/_index.md#namespaced-paths) |
| `confidential` | boolean | no | **Deprecated:** Scheduled to 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`. |
```plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id
```9
### Modify existing epic note
Modify existing note of an epic.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```0
Parameters:
| Attribute | Type | Required | Description |
|----------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
| `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:** Scheduled to be removed in GitLab 16.0. The confidential flag of a note. Default is false. |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```1
### Delete an epic note
Deletes an existing note of an epic.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```2
Parameters:
| Attribute | Type | Required | Description |
|-----------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```3
## Project wikis
### List all project wiki notes
Gets a list of all notes for a project wiki page. Project wiki notes are comments users can post to a wiki page.
The wiki page notes API uses the wiki page meta ID instead of wiki page slug. If you use the page's slug, GitLab returns a 404
error. You can retrieve the meta ID from the [project wikis API](wikis.md).
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```4
Parameters:
| Attribute | Type | Required | Description |
|------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `sort` | string | no | Return wiki page notes sorted in `asc` or `desc` order. Default is `desc` |
| `order_by` | string | no | Return wiki page notes ordered by `created_at` or `updated_at` fields. Default is `created_at` |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```5
### Get single wiki page note
Returns a single note for a given wiki page.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```6
Parameters:
| Attribute | Type | Required | Description |
|-----------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `note_id` | integer | yes | The ID of a note |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```7
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```8
### Create new wiki page note
Creates a new note for a single wiki page. Wiki page notes are comments users can post to a wiki page.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
```9
Parameters:
| Attribute | Type | Required | Description |
|----------------|-------------------|----------|-------------|
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```0
### Modify existing wiki page note
Modifies an existing note on a wiki page.
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```1
Parameters:
| Attribute | Type | Required | Description |
|----------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `note_id` | integer | yes | The ID of a note |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```2
### Delete a wiki page note
Deletes a note from a wiki page.
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```3
Parameters:
| Attribute | Type | Required | Description |
|-----------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `note_id` | integer | yes | The ID of a note |
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```4
## Group wikis
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
### List all group wiki notes
Gets a list of all notes for a group wiki page. Group wiki notes are comments users can post to a wiki page.
The wiki page notes API uses the wiki page meta ID instead of wiki page slug. If you use the page's slug, GitLab returns a 404
error. You can retrieve the meta ID from the [group wikis API](group_wikis.md).
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```5
| Attribute | Type | Required | Description |
|------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `sort` | string | no | Return wiki page notes sorted in `asc` or `desc` order. Default is `desc` |
| `order_by` | string | no | Return wiki page notes ordered by `created_at` or `updated_at` fields. Default is `created_at` |
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```6
### Get single wiki page note
Returns a single note for a given wiki page.
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```7
Parameters:
| Attribute | Type | Required | Description |
|-----------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `note_id` | integer | yes | The ID of a note |
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```8
```plaintext
POST /projects/:id/issues/:issue_iid/notes
```9
### Create new wiki page note
Creates a new note for a single wiki page. Wiki page notes are comments users can post to a wiki page.
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
```0
Parameters:
| Attribute | Type | Required | Description |
|----------------|-------------------|----------|-------------|
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
```1
### Modify existing wiki page note
Modifies an existing note on a wiki page.
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
```2
Parameters:
| Attribute | Type | Required | Description |
|----------------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `note_id` | integer | yes | The ID of a note |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
```3
### Delete a wiki page note
Deletes a note from a wiki page.
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
```4
Parameters:
| Attribute | Type | Required | Description |
|-----------|-------------------|----------|-------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/_index.md#namespaced-paths) |
| `wiki_page_meta_id` | integer | yes | The ID of a wiki page meta |
| `note_id` | integer | yes | The ID of a note |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
```5