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

384 lines
12 KiB
Markdown
Raw Normal View History

2017-09-10 17:25:29 +05:30
# Notes API
2014-09-02 18:07:02 +05:30
Notes are comments on snippets, issues or merge requests.
## Issues
### List project issue notes
Gets a list of all notes for a single issue.
2014-09-02 18:07:02 +05:30
```
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 |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2018-03-27 19:54:05 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.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,
"resolvable": 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,
"resolvable": false
2014-09-02 18:07:02 +05:30
}
]
```
2018-03-27 19:54:05 +05:30
```bash
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes
```
2014-09-02 18:07:02 +05:30
### Get single issue note
Returns a single note for a specific project issue
```
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:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2017-08-17 22:00:37 +05:30
- `issue_iid` (required) - The IID of a project issue
2014-09-02 18:07:02 +05:30
- `note_id` (required) - The ID of an issue note
2018-03-27 19:54:05 +05:30
```bash
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1
```
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
```
2017-08-17 22:00:37 +05:30
POST /projects/:id/issues/:issue_iid/notes
2014-09-02 18:07:02 +05:30
```
Parameters:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2017-08-17 22:00:37 +05:30
- `issue_id` (required) - The IID of an issue
2014-09-02 18:07:02 +05:30
- `body` (required) - The content of a note
2018-11-20 20:47:30 +05:30
- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
2014-09-02 18:07:02 +05:30
2018-03-27 19:54:05 +05:30
```bash
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note
```
2015-04-26 12:48:37 +05:30
### Modify existing issue note
Modify existing note of an issue.
```
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:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2017-08-17 22:00:37 +05:30
- `issue_iid` (required) - The IID of an issue
2015-04-26 12:48:37 +05:30
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note
2018-03-27 19:54:05 +05:30
```bash
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note
```
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
```
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 |
| --------- | ---- | -------- | ----------- |
2018-03-27 19:54:05 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.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 |
```bash
2017-08-17 22:00:37 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 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
### List all snippet notes
Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.
```
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 |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2018-03-27 19:54:05 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.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
2018-03-27 19:54:05 +05:30
```bash
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes
```
2014-09-02 18:07:02 +05:30
### Get single snippet note
Returns a single note for a given snippet.
```
GET /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2014-09-02 18:07:02 +05:30
- `snippet_id` (required) - The ID of a project snippet
2018-03-17 18:26:18 +05:30
- `note_id` (required) - 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"
}
```
2018-03-27 19:54:05 +05:30
```bash
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11
```
2014-09-02 18:07:02 +05:30
### Create new snippet note
Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet.
2016-09-29 09:46:39 +05:30
If you create a note where the body only contains an Award Emoji, you'll receive this object back.
2014-09-02 18:07:02 +05:30
```
POST /projects/:id/snippets/:snippet_id/notes
```
Parameters:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2015-04-26 12:48:37 +05:30
- `snippet_id` (required) - The ID of a snippet
- `body` (required) - The content of a note
2018-11-18 11:00:15 +05:30
- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z
2015-04-26 12:48:37 +05:30
2018-03-27 19:54:05 +05:30
```bash
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note
```
2015-04-26 12:48:37 +05:30
### Modify existing snippet note
Modify existing note of a snippet.
```
PUT /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2015-04-26 12:48:37 +05:30
- `snippet_id` (required) - The ID of a snippet
- `note_id` (required) - The ID of a note
2014-09-02 18:07:02 +05:30
- `body` (required) - The content of a note
2018-03-27 19:54:05 +05:30
```bash
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note
```
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
```
DELETE /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2018-03-27 19:54:05 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.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 |
```bash
2017-08-17 22:00:37 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659
2016-06-02 11:05:42 +05:30
```
2014-09-02 18:07:02 +05:30
## Merge Requests
### List all merge request notes
Gets a list of all notes for a single merge request.
```
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 |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2018-03-27 19:54:05 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.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
2018-03-27 19:54:05 +05:30
```bash
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes
```
2014-09-02 18:07:02 +05:30
### Get single merge request note
Returns a single note for a given merge request.
```
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:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2017-08-17 22:00:37 +05:30
- `merge_request_iid` (required) - The IID of a project merge request
2014-09-02 18:07:02 +05:30
- `note_id` (required) - The ID of a merge request note
```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,
"resolvable": false
2014-09-02 18:07:02 +05:30
}
```
2018-03-27 19:54:05 +05:30
```bash
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1
```
2014-09-02 18:07:02 +05:30
### Create new merge request note
Creates a new note for a single merge request.
2016-09-29 09:46:39 +05:30
If you create a note where the body only contains an Award Emoji, you'll receive
this object back.
2014-09-02 18:07:02 +05:30
```
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:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2017-08-17 22:00:37 +05:30
- `merge_request_iid` (required) - The IID of a merge request
2014-09-02 18:07:02 +05:30
- `body` (required) - The content of a note
2018-11-18 11:00:15 +05:30
- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z
2015-04-26 12:48:37 +05:30
### Modify existing merge request note
Modify existing note of a merge request.
```
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:
2018-03-27 19:54:05 +05:30
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
2017-08-17 22:00:37 +05:30
- `merge_request_iid` (required) - The IID of a merge request
2015-04-26 12:48:37 +05:30
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note
2016-06-02 11:05:42 +05:30
2018-03-27 19:54:05 +05:30
```bash
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note
```
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
```
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 |
| --------- | ---- | -------- | ----------- |
2018-03-27 19:54:05 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.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 |
```bash
2017-08-17 22:00:37 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602
2016-06-02 11:05:42 +05:30
```