notes.md 12.4 KB
Newer Older
1
# Notes API
Marin Jankovski's avatar
Marin Jankovski committed
2

3
Notes are comments on snippets, issues or merge requests.
4 5 6 7 8

## Issues

### List project issue notes

9
Gets a list of all notes for a single issue.
Nihad Abbasov's avatar
Nihad Abbasov committed
10 11

```
12
GET /projects/:id/issues/:issue_iid/notes
13
GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at
Nihad Abbasov's avatar
Nihad Abbasov committed
14 15
```

16 17
| Attribute           | Type             | Required   | Description                                                                                                                                         |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
Jan Provaznik's avatar
Jan Provaznik committed
18
| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
19 20 21
| `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`
Nihad Abbasov's avatar
Nihad Abbasov committed
22

23 24 25
```json
[
  {
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
26
    "id": 302,
27
    "body": "closed",
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
28 29 30 31 32 33 34 35
    "attachment": null,
    "author": {
      "id": 1,
      "username": "pipin",
      "email": "admin@example.com",
      "name": "Pip",
      "state": "active",
      "created_at": "2013-09-30T13:46:01Z"
36
    },
37
    "created_at": "2013-10-02T09:22:45Z",
38
    "updated_at": "2013-10-02T10:22:45Z",
39
    "system": true,
40
    "noteable_id": 377,
sue445's avatar
sue445 committed
41
    "noteable_type": "Issue",
42 43
    "noteable_iid": 377,
    "resolvable": false
44 45
  },
  {
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
46 47 48 49 50 51 52 53 54 55
    "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"
56
    },
57
    "created_at": "2013-10-02T09:56:03Z",
58
    "updated_at": "2013-10-02T09:56:03Z",
59
    "system": true,
60
    "noteable_id": 121,
sue445's avatar
sue445 committed
61
    "noteable_type": "Issue",
62 63
    "noteable_iid": 121,
    "resolvable": false
64 65 66
  }
]
```
67

Jan Provaznik's avatar
Jan Provaznik committed
68
```bash
69
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes
Jan Provaznik's avatar
Jan Provaznik committed
70 71
```

72 73 74
### Get single issue note

Returns a single note for a specific project issue
Nihad Abbasov's avatar
Nihad Abbasov committed
75 76

```
77
GET /projects/:id/issues/:issue_iid/notes/:note_id
Nihad Abbasov's avatar
Nihad Abbasov committed
78 79 80 81
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
82
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
83
- `issue_iid` (required) - The IID of a project issue
Ciro Santilli's avatar
Ciro Santilli committed
84
- `note_id` (required) - The ID of an issue note
Nihad Abbasov's avatar
Nihad Abbasov committed
85

Jan Provaznik's avatar
Jan Provaznik committed
86
```bash
87
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1
Jan Provaznik's avatar
Jan Provaznik committed
88 89
```

90
### Create new issue note
Nihad Abbasov's avatar
Nihad Abbasov committed
91

Jan Provaznik's avatar
Jan Provaznik committed
92
Creates a new note to a single project issue.
Nihad Abbasov's avatar
Nihad Abbasov committed
93 94

```
95
POST /projects/:id/issues/:issue_iid/notes
Nihad Abbasov's avatar
Nihad Abbasov committed
96 97 98 99
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
100
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
101
- `issue_iid` (required) - The IID of an issue
Ciro Santilli's avatar
Ciro Santilli committed
102
- `body` (required) - The content of a note
103
- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
104

Jan Provaznik's avatar
Jan Provaznik committed
105
```bash
106
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note
Jan Provaznik's avatar
Jan Provaznik committed
107 108
```

109 110 111 112 113
### Modify existing issue note

Modify existing note of an issue.

```
114
PUT /projects/:id/issues/:issue_iid/notes/:note_id
115 116 117 118
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
119
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
120
- `issue_iid` (required) - The IID of an issue
121 122 123
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note

Jan Provaznik's avatar
Jan Provaznik committed
124
```bash
125
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note
Jan Provaznik's avatar
Jan Provaznik committed
126 127
```

Robert Schilling's avatar
Robert Schilling committed
128
### Delete an issue note
Robert Schilling's avatar
Robert Schilling committed
129

130
Deletes an existing note of an issue.
Robert Schilling's avatar
Robert Schilling committed
131 132

```
133
DELETE /projects/:id/issues/:issue_iid/notes/:note_id
Robert Schilling's avatar
Robert Schilling committed
134 135 136 137
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
138 139
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Jan Provaznik's avatar
Jan Provaznik committed
140
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
141
| `issue_iid` | integer | yes | The IID of an issue |
Robert Schilling's avatar
Robert Schilling committed
142 143 144
| `note_id` | integer | yes | The ID of a note |

```bash
145
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636
Robert Schilling's avatar
Robert Schilling committed
146 147
```

148 149 150 151 152
## 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.
Nihad Abbasov's avatar
Nihad Abbasov committed
153 154

```
155
GET /projects/:id/snippets/:snippet_id/notes
156
GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at
Nihad Abbasov's avatar
Nihad Abbasov committed
157 158
```

159 160
| Attribute           | Type             | Required   | Description                                                                                                                                         |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
Jan Provaznik's avatar
Jan Provaznik committed
161
| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
162 163 164
| `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`
Nihad Abbasov's avatar
Nihad Abbasov committed
165

Jan Provaznik's avatar
Jan Provaznik committed
166
```bash
167
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes
Jan Provaznik's avatar
Jan Provaznik committed
168 169
```

170
### Get single snippet note
Nihad Abbasov's avatar
Nihad Abbasov committed
171

172
Returns a single note for a given snippet.
Nihad Abbasov's avatar
Nihad Abbasov committed
173 174

```
175
GET /projects/:id/snippets/:snippet_id/notes/:note_id
Nihad Abbasov's avatar
Nihad Abbasov committed
176 177 178 179
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
180
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
Ciro Santilli's avatar
Ciro Santilli committed
181
- `snippet_id` (required) - The ID of a project snippet
Ville Skyttä's avatar
Ville Skyttä committed
182
- `note_id` (required) - The ID of a snippet note
Nihad Abbasov's avatar
Nihad Abbasov committed
183

184 185
```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
186 187 188 189 190 191 192 193 194 195
  "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"
196
  },
197
  "expires_at": null,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
198 199
  "updated_at": "2013-10-02T07:34:20Z",
  "created_at": "2013-10-02T07:34:20Z"
200 201
}
```
202

Jan Provaznik's avatar
Jan Provaznik committed
203
```bash
204
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11
Jan Provaznik's avatar
Jan Provaznik committed
205 206
```

207 208 209
### Create new snippet note

Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet.
210
If you create a note where the body only contains an Award Emoji, you'll receive this object back.
211 212

```
213
POST /projects/:id/snippets/:snippet_id/notes
214 215 216 217
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
218
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
219 220
- `snippet_id` (required) - The ID of a snippet
- `body` (required) - The content of a note
221
- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z
222

Jan Provaznik's avatar
Jan Provaznik committed
223
```bash
224
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note
Jan Provaznik's avatar
Jan Provaznik committed
225 226
```

227 228 229 230 231 232 233 234 235 236
### Modify existing snippet note

Modify existing note of a snippet.

```
PUT /projects/:id/snippets/:snippet_id/notes/:note_id
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
237
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
238 239
- `snippet_id` (required) - The ID of a snippet
- `note_id` (required) - The ID of a note
Ciro Santilli's avatar
Ciro Santilli committed
240
- `body` (required) - The content of a note
241

Jan Provaznik's avatar
Jan Provaznik committed
242
```bash
243
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note
Jan Provaznik's avatar
Jan Provaznik committed
244 245
```

Robert Schilling's avatar
Robert Schilling committed
246
### Delete a snippet note
Robert Schilling's avatar
Robert Schilling committed
247

248
Deletes an existing note of a snippet.
Robert Schilling's avatar
Robert Schilling committed
249 250 251 252 253 254 255

```
DELETE /projects/:id/snippets/:snippet_id/notes/:note_id
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
256 257
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Jan Provaznik's avatar
Jan Provaznik committed
258
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
Robert Schilling's avatar
Robert Schilling committed
259 260 261 262
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a note |

```bash
263
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659
Robert Schilling's avatar
Robert Schilling committed
264 265
```

266 267 268 269 270
## Merge Requests

### List all merge request notes

Gets a list of all notes for a single merge request.
Nihad Abbasov's avatar
Nihad Abbasov committed
271 272

```
273
GET /projects/:id/merge_requests/:merge_request_iid/notes
274
GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=updated_at
Nihad Abbasov's avatar
Nihad Abbasov committed
275 276
```

277 278
| Attribute           | Type             | Required   | Description                                                                                                                                         |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
Jan Provaznik's avatar
Jan Provaznik committed
279
| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
280 281 282
| `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`
Nihad Abbasov's avatar
Nihad Abbasov committed
283

Jan Provaznik's avatar
Jan Provaznik committed
284
```bash
285
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes
Jan Provaznik's avatar
Jan Provaznik committed
286 287
```

288 289 290
### Get single merge request note

Returns a single note for a given merge request.
Nihad Abbasov's avatar
Nihad Abbasov committed
291 292

```
293
GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
Nihad Abbasov's avatar
Nihad Abbasov committed
294 295 296 297
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
298
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
299
- `merge_request_iid` (required) - The IID of a project merge request
Ciro Santilli's avatar
Ciro Santilli committed
300
- `note_id` (required) - The ID of a merge request note
301

302 303
```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
304 305 306 307 308 309 310 311 312 313
  "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"
314
  },
315
  "created_at": "2013-10-02T08:57:14Z",
316
  "updated_at": "2013-10-02T08:57:14Z",
317 318
  "system": false,
  "noteable_id": 2,
sue445's avatar
sue445 committed
319
  "noteable_type": "MergeRequest",
320 321
  "noteable_iid": 2,
  "resolvable": false
322 323
}
```
324

Jan Provaznik's avatar
Jan Provaznik committed
325
```bash
326
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1
Jan Provaznik's avatar
Jan Provaznik committed
327 328
```

329 330 331
### Create new merge request note

Creates a new note for a single merge request.
332 333
If you create a note where the body only contains an Award Emoji, you'll receive
this object back.
334 335

```
336
POST /projects/:id/merge_requests/:merge_request_iid/notes
337 338 339 340
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
341
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
342
- `merge_request_iid` (required) - The IID of a merge request
Ciro Santilli's avatar
Ciro Santilli committed
343
- `body` (required) - The content of a note
344
- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z
345 346 347 348 349 350

### Modify existing merge request note

Modify existing note of a merge request.

```
351
PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
352 353 354 355
```

Parameters:

Jan Provaznik's avatar
Jan Provaznik committed
356
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding)
357
- `merge_request_iid` (required) - The IID of a merge request
358 359
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note
Robert Schilling's avatar
Robert Schilling committed
360

Jan Provaznik's avatar
Jan Provaznik committed
361
```bash
362
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note
Jan Provaznik's avatar
Jan Provaznik committed
363 364
```

Robert Schilling's avatar
Robert Schilling committed
365
### Delete a merge request note
Robert Schilling's avatar
Robert Schilling committed
366

367
Deletes an existing note of a merge request.
Robert Schilling's avatar
Robert Schilling committed
368 369

```
370
DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
Robert Schilling's avatar
Robert Schilling committed
371 372 373 374
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
375 376
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Jan Provaznik's avatar
Jan Provaznik committed
377
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
378
| `merge_request_iid` | integer | yes | The IID of a merge request |
Robert Schilling's avatar
Robert Schilling committed
379 380 381
| `note_id` | integer | yes | The ID of a note |

```bash
382
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602
Robert Schilling's avatar
Robert Schilling committed
383
```