debian-mirror-gitlab/doc/api/notes.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

580 lines
25 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
stage: Plan
group: Project Management
2021-02-22 17:27:13 +05:30
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
2021-01-29 00:20:46 +05:30
---
2021-06-08 01:23:25 +05:30
# Notes API **(FREE)**
2014-09-02 18:07:02 +05:30
2019-09-04 21:01:54 +05:30
Notes are comments on:
- Snippets
- Issues
- Merge requests
2021-03-08 18:12:59 +05:30
- Epics **(PREMIUM)**
2014-09-02 18:07:02 +05:30
2020-10-24 23:57:45 +05:30
This includes system notes, which are notes about changes to the object (for example, when an
2021-02-22 17:27:13 +05:30
assignee changes, GitLab posts a system note).
2020-10-24 23:57:45 +05:30
## Resource events
2020-11-24 15:15:51 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38096) in GitLab 13.3 for state, milestone, and weight events.
2021-06-08 01:23:25 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40850) in GitLab 13.4 for iteration events.
2020-10-24 23:57:45 +05:30
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-06-08 01:23:25 +05:30
- [Resource weight events](resource_weight_events.md)
- [Resource iteration events](resource_iteration_events.md)
2019-07-31 22:56:46 +05:30
## Notes pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
2021-09-30 23:02:18 +05:30
Read more on [pagination](index.md#pagination).
2019-07-31 22:56:46 +05:30
2021-03-11 19:13:27 +05:30
## 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).
2014-09-02 18:07:02 +05:30
## Issues
### List project issue notes
Gets a list of all notes for a single issue.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/issues/:issue_iid/notes
2018-03-17 18:26:18 +05:30
GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at
2014-09-02 18:07:02 +05:30
```
2018-03-17 18:26:18 +05:30
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
2018-03-17 18:26:18 +05:30
| `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`
2014-09-02 18:07:02 +05:30
```json
[
{
"id": 302,
2017-08-17 22:00:37 +05:30
"body": "closed",
2014-09-02 18:07:02 +05:30
"attachment": null,
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
2015-09-11 14:41:01 +05:30
"created_at": "2013-10-02T09:22:45Z",
2016-06-02 11:05:42 +05:30
"updated_at": "2013-10-02T10:22:45Z",
2015-09-11 14:41:01 +05:30
"system": true,
2015-12-23 02:04:40 +05:30
"noteable_id": 377,
2017-09-10 17:25:29 +05:30
"noteable_type": "Issue",
2018-10-15 14:42:47 +05:30
"noteable_iid": 377,
2020-04-22 19:07:51 +05:30
"resolvable": false,
"confidential": false
2014-09-02 18:07:02 +05:30
},
{
"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"
},
2015-09-11 14:41:01 +05:30
"created_at": "2013-10-02T09:56:03Z",
2016-06-02 11:05:42 +05:30
"updated_at": "2013-10-02T09:56:03Z",
2015-11-26 14:37:03 +05:30
"system": true,
2015-12-23 02:04:40 +05:30
"noteable_id": 121,
2017-09-10 17:25:29 +05:30
"noteable_type": "Issue",
2018-10-15 14:42:47 +05:30
"noteable_iid": 121,
2020-04-22 19:07:51 +05:30
"resolvable": false,
"confidential": true
2014-09-02 18:07:02 +05:30
}
]
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
2018-03-27 19:54:05 +05:30
```
2014-09-02 18:07:02 +05:30
### Get single issue note
Returns a single note for a specific project issue
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/issues/:issue_iid/notes/:note_id
2014-09-02 18:07:02 +05:30
```
Parameters:
2022-01-26 12:08:38 +05:30
| 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 |
2014-09-02 18:07:02 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
2018-03-27 19:54:05 +05:30
```
2014-09-02 18:07:02 +05:30
### Create new issue note
2018-03-27 19:54:05 +05:30
Creates a new note to a single project issue.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/issues/:issue_iid/notes
2014-09-02 18:07:02 +05:30
```
Parameters:
2022-01-26 12:08:38 +05:30
| Attribute | Type | Required | Description |
|----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
2022-06-21 17:19:12 +05:30
| `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. |
2022-01-26 12:08:38 +05:30
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `confidential` | boolean | no | The confidential flag of a note. Default is false. |
| `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 18:07:02 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
2018-03-27 19:54:05 +05:30
```
2015-04-26 12:48:37 +05:30
### Modify existing issue note
Modify existing note of an issue.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/issues/:issue_iid/notes/:note_id
2015-04-26 12:48:37 +05:30
```
Parameters:
2022-06-21 17:19:12 +05:30
| 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. |
2015-04-26 12:48:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
2018-03-27 19:54:05 +05:30
```
2016-06-02 11:05:42 +05:30
### Delete an issue note
2017-08-17 22:00:37 +05:30
Deletes an existing note of an issue.
2016-06-02 11:05:42 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/issues/:issue_iid/notes/:note_id
2016-06-02 11:05:42 +05:30
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
2017-08-17 22:00:37 +05:30
| `issue_iid` | integer | yes | The IID of an issue |
2016-06-02 11:05:42 +05:30
| `note_id` | integer | yes | The ID of a note |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636"
2016-06-02 11:05:42 +05:30
```
2014-09-02 18:07:02 +05:30
## Snippets
2021-03-08 18:12:59 +05:30
The Snippets Notes API is intended for project-level snippets, and not for personal snippets.
2014-09-02 18:07:02 +05:30
### List all snippet notes
Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.
2020-04-08 14:13:33 +05:30
```plaintext
2014-09-02 18:07:02 +05:30
GET /projects/:id/snippets/:snippet_id/notes
2018-03-17 18:26:18 +05:30
GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at
2014-09-02 18:07:02 +05:30
```
2018-03-17 18:26:18 +05:30
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
2018-03-17 18:26:18 +05:30
| `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`
2014-09-02 18:07:02 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes"
2018-03-27 19:54:05 +05:30
```
2014-09-02 18:07:02 +05:30
### Get single snippet note
Returns a single note for a given snippet.
2020-04-08 14:13:33 +05:30
```plaintext
2014-09-02 18:07:02 +05:30
GET /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
2022-01-26 12:08:38 +05:30
| 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 |
2014-09-02 18:07:02 +05:30
```json
{
"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"
},
"expires_at": null,
"updated_at": "2013-10-02T07:34:20Z",
"created_at": "2013-10-02T07:34:20Z"
}
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11"
2018-03-27 19:54:05 +05:30
```
2014-09-02 18:07:02 +05:30
### Create new snippet note
2021-02-22 17:27:13 +05:30
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.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2014-09-02 18:07:02 +05:30
POST /projects/:id/snippets/:snippet_id/notes
```
Parameters:
2022-01-26 12:08:38 +05:30
| 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) |
2015-04-26 12:48:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note"
2018-03-27 19:54:05 +05:30
```
2015-04-26 12:48:37 +05:30
### Modify existing snippet note
Modify existing note of a snippet.
2020-04-08 14:13:33 +05:30
```plaintext
2015-04-26 12:48:37 +05:30
PUT /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
2022-01-26 12:08:38 +05:30
| 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. |
2014-09-02 18:07:02 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note"
2018-03-27 19:54:05 +05:30
```
2016-06-02 11:05:42 +05:30
### Delete a snippet note
2017-08-17 22:00:37 +05:30
Deletes an existing note of a snippet.
2016-06-02 11:05:42 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2016-06-02 11:05:42 +05:30
DELETE /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
2016-06-02 11:05:42 +05:30
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a note |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659"
2016-06-02 11:05:42 +05:30
```
2022-04-04 11:22:00 +05:30
## Merge requests
2014-09-02 18:07:02 +05:30
### List all merge request notes
Gets a list of all notes for a single merge request.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/notes
2018-03-17 18:26:18 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=updated_at
2014-09-02 18:07:02 +05:30
```
2018-03-17 18:26:18 +05:30
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
2018-03-17 18:26:18 +05:30
| `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`
2014-09-02 18:07:02 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes"
2018-03-27 19:54:05 +05:30
```
2014-09-02 18:07:02 +05:30
### Get single merge request note
Returns a single note for a given merge request.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
2014-09-02 18:07:02 +05:30
```
Parameters:
2022-01-26 12:08:38 +05:30
| 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 |
2014-09-02 18:07:02 +05:30
```json
{
"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"
},
2015-12-23 02:04:40 +05:30
"created_at": "2013-10-02T08:57:14Z",
2016-06-02 11:05:42 +05:30
"updated_at": "2013-10-02T08:57:14Z",
2015-12-23 02:04:40 +05:30
"system": false,
"noteable_id": 2,
2017-09-10 17:25:29 +05:30
"noteable_type": "MergeRequest",
2018-10-15 14:42:47 +05:30
"noteable_iid": 2,
2020-04-22 19:07:51 +05:30
"resolvable": false,
"confidential": false
2014-09-02 18:07:02 +05:30
}
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1"
2018-03-27 19:54:05 +05:30
```
2014-09-02 18:07:02 +05:30
### Create new merge request note
Creates a new note for a single merge request.
2021-02-22 17:27:13 +05:30
If you create a note where the body only contains an Award Emoji, GitLab returns this object.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/notes
2014-09-02 18:07:02 +05:30
```
Parameters:
2022-01-26 12:08:38 +05:30
| Attribute | Type | Required | Description |
|---------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
2022-05-07 20:08:51 +05:30
| `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-06-21 17:19:12 +05:30
| `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. |
2015-04-26 12:48:37 +05:30
### Modify existing merge request note
Modify existing note of a merge request.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
2015-04-26 12:48:37 +05:30
```
Parameters:
2022-06-21 17:19:12 +05:30
| 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-06-02 11:05:42 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note"
2018-03-27 19:54:05 +05:30
```
2016-06-02 11:05:42 +05:30
### Delete a merge request note
2017-08-17 22:00:37 +05:30
Deletes an existing note of a merge request.
2016-06-02 11:05:42 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
2016-06-02 11:05:42 +05:30
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
2017-08-17 22:00:37 +05:30
| `merge_request_iid` | integer | yes | The IID of a merge request |
2016-06-02 11:05:42 +05:30
| `note_id` | integer | yes | The ID of a note |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602"
2016-06-02 11:05:42 +05:30
```
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
## Epics **(ULTIMATE)**
2019-09-04 21:01:54 +05:30
### 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-06-21 17:19:12 +05:30
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-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
GET /groups/:id/epics/:epic_id/notes
GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ----------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
2019-09-04 21:01:54 +05:30
| `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-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes"
2019-09-04 21:01:54 +05:30
```
### Get single epic note
Returns a single note for a given epic.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
GET /groups/:id/epics/:epic_id/notes/:note_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
2019-09-04 21:01:54 +05:30
| `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-04-22 19:07:51 +05:30
"created_at": "2013-10-02T07:34:20Z",
"confidential": false
2019-09-04 21:01:54 +05:30
}
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1"
2019-09-04 21:01:54 +05:30
```
### Create new epic note
Creates a new note for a single epic. Epic notes are comments users can post to an epic.
2021-02-22 17:27:13 +05:30
If you create a note where the body only contains an Award Emoji, GitLab returns this object.
2019-09-04 21:01:54 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
POST /groups/:id/epics/:epic_id/notes
```
Parameters:
2022-06-21 17:19:12 +05:30
| 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) |
| `confidential` | boolean | no | The confidential flag of a note. Default is `false`. |
2019-09-04 21:01:54 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-06-08 01:23:25 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note"
2019-09-04 21:01:54 +05:30
```
### Modify existing epic note
Modify existing note of an epic.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
PUT /groups/:id/epics/:epic_id/notes/:note_id
```
Parameters:
2022-06-21 17:19:12 +05:30
| 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-09-04 21:01:54 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-06-08 01:23:25 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note"
2019-09-04 21:01:54 +05:30
```
### Delete an epic note
Deletes an existing note of an epic.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
DELETE /groups/:id/epics/:epic_id/notes/:note_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
2022-01-26 12:08:38 +05:30
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
2019-09-04 21:01:54 +05:30
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/52/notes/1659"
2019-09-04 21:01:54 +05:30
```