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

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
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 13 14 15 16

```
GET /projects/:id/issues/:issue_id/notes
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
17
- `id` (required) - The ID of a project
18
- `issue_id` (required) - The ID of an issue
Nihad Abbasov's avatar
Nihad Abbasov committed
19

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

### Get single issue note

Returns a single note for a specific project issue
Nihad Abbasov's avatar
Nihad Abbasov committed
68 69

```
70
GET /projects/:id/issues/:issue_id/notes/:note_id
Nihad Abbasov's avatar
Nihad Abbasov committed
71 72 73 74
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
75
- `id` (required) - The ID of a project
76
- `issue_id` (required) - The ID of a project issue
Ciro Santilli's avatar
Ciro Santilli committed
77
- `note_id` (required) - The ID of an issue note
Nihad Abbasov's avatar
Nihad Abbasov committed
78

79
### Create new issue note
Nihad Abbasov's avatar
Nihad Abbasov committed
80

81
Creates a new note to a single project issue.
Nihad Abbasov's avatar
Nihad Abbasov committed
82 83

```
84
POST /projects/:id/issues/:issue_id/notes
Nihad Abbasov's avatar
Nihad Abbasov committed
85 86 87 88
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
89
- `id` (required) - The ID of a project
90
- `issue_id` (required) - The ID of an issue
Ciro Santilli's avatar
Ciro Santilli committed
91
- `body` (required) - The content of a note
92
- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z
93

94 95 96 97 98 99 100 101 102 103 104
### Modify existing issue note

Modify existing note of an issue.

```
PUT /projects/:id/issues/:issue_id/notes/:note_id
```

Parameters:

- `id` (required) - The ID of a project
105
- `issue_id` (required) - The ID of an issue
106 107 108
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note

Robert Schilling's avatar
Robert Schilling committed
109
### Delete an issue note
Robert Schilling's avatar
Robert Schilling committed
110

Robert Schilling's avatar
Robert Schilling committed
111 112
Deletes an existing note of an issue. On success, this API method returns 200
and the deleted note. If the note does not exist, the API returns 404.
Robert Schilling's avatar
Robert Schilling committed
113 114 115 116 117 118 119

```
DELETE /projects/:id/issues/:issue_id/notes/:note_id
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
120 121 122
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
123
| `issue_id` | integer | yes | The ID of an issue |
Robert Schilling's avatar
Robert Schilling committed
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
| `note_id` | integer | yes | The ID of a note |

```bash
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/11/notes/636
```

Example Response:

```json
{
  "id": 636,
  "body": "This is a good idea.",
  "attachment": null,
  "author": {
    "id": 1,
    "username": "pipin",
    "email": "admin@example.com",
    "name": "Pip",
    "state": "active",
    "created_at": "2013-09-30T13:46:01Z",
    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/u/pipin"
  },
  "created_at": "2016-04-05T22:10:44.164Z",
  "system": false,
  "noteable_id": 11,
  "noteable_type": "Issue",
  "upvote": false,
  "downvote": false
}
```
Robert Schilling's avatar
Robert Schilling committed
155

156 157 158 159 160
## 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
161 162

```
163
GET /projects/:id/snippets/:snippet_id/notes
Nihad Abbasov's avatar
Nihad Abbasov committed
164 165 166 167
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
168 169
- `id` (required) - The ID of a project
- `snippet_id` (required) - The ID of a project snippet
Nihad Abbasov's avatar
Nihad Abbasov committed
170

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

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

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

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
181 182 183
- `id` (required) - The ID of a project
- `snippet_id` (required) - The ID of a project snippet
- `note_id` (required) - The ID of an snippet note
Nihad Abbasov's avatar
Nihad Abbasov committed
184

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

### Create new snippet note

Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet.
207 208

```
209
POST /projects/:id/snippets/:snippet_id/notes
210 211 212 213
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
214
- `id` (required) - The ID of a project
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
- `snippet_id` (required) - The ID of a snippet
- `body` (required) - The content of a note

### Modify existing snippet note

Modify existing note of a snippet.

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

Parameters:

- `id` (required) - The ID of a project
- `snippet_id` (required) - The ID of a snippet
- `note_id` (required) - The ID of a note
Ciro Santilli's avatar
Ciro Santilli committed
231
- `body` (required) - The content of a note
232

Robert Schilling's avatar
Robert Schilling committed
233
### Delete a snippet note
Robert Schilling's avatar
Robert Schilling committed
234

Robert Schilling's avatar
Robert Schilling committed
235 236
Deletes an existing note of a snippet. On success, this API method returns 200
and the deleted note. If the note does not exist, the API returns 404.
Robert Schilling's avatar
Robert Schilling committed
237 238 239 240 241 242 243

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

Parameters:

Robert Schilling's avatar
Robert Schilling committed
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a note |

```bash
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/snippets/52/notes/1659
```

Example Response:

```json
{
  "id": 1659,
  "body": "This is a good idea.",
  "attachment": null,
  "author": {
    "id": 1,
    "username": "pipin",
    "email": "admin@example.com",
    "name": "Pip",
    "state": "active",
    "created_at": "2013-09-30T13:46:01Z",
    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/u/pipin"
  },
  "created_at": "2016-04-06T16:51:53.239Z",
  "system": false,
  "noteable_id": 52,
  "noteable_type": "Snippet",
  "upvote": false,
  "downvote": false
}
```
Robert Schilling's avatar
Robert Schilling committed
279

280 281 282 283 284
## 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
285 286

```
287
GET /projects/:id/merge_requests/:merge_request_id/notes
Nihad Abbasov's avatar
Nihad Abbasov committed
288 289 290 291
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
292 293
- `id` (required) - The ID of a project
- `merge_request_id` (required) - The ID of a project merge request
Nihad Abbasov's avatar
Nihad Abbasov committed
294

295 296 297
### Get single merge request note

Returns a single note for a given merge request.
Nihad Abbasov's avatar
Nihad Abbasov committed
298 299

```
300
GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id
Nihad Abbasov's avatar
Nihad Abbasov committed
301 302 303 304
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
305 306 307
- `id` (required) - The ID of a project
- `merge_request_id` (required) - The ID of a project merge request
- `note_id` (required) - The ID of a merge request note
308

309 310
```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
311 312 313 314 315 316 317 318 319 320
  "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"
321
  },
322
  "created_at": "2013-10-02T08:57:14Z",
323
  "updated_at": "2013-10-02T08:57:14Z",
324 325 326 327 328
  "system": false,
  "upvote": false,
  "downvote": false,
  "noteable_id": 2,
  "noteable_type": "MergeRequest"
329 330
}
```
331 332 333 334 335 336 337 338 339 340 341

### Create new merge request note

Creates a new note for a single merge request.

```
POST /projects/:id/merge_requests/:merge_request_id/notes
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
342 343 344
- `id` (required) - The ID of a project
- `merge_request_id` (required) - The ID of a merge request
- `body` (required) - The content of a note
345 346 347 348 349 350 351 352 353 354 355 356 357 358 359

### Modify existing merge request note

Modify existing note of a merge request.

```
PUT /projects/:id/merge_requests/:merge_request_id/notes/:note_id
```

Parameters:

- `id` (required) - The ID of a project
- `merge_request_id` (required) - The ID of a merge request
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note
Robert Schilling's avatar
Robert Schilling committed
360

Robert Schilling's avatar
Robert Schilling committed
361
### Delete a merge request note
Robert Schilling's avatar
Robert Schilling committed
362 363

Deletes an existing note of a merge request. On success, this API method returns
Robert Schilling's avatar
Robert Schilling committed
364
200 and the deleted note. If the note does not exist, the API returns 404.
Robert Schilling's avatar
Robert Schilling committed
365 366 367 368 369 370 371

```
DELETE /projects/:id/merge_requests/:merge_request_id/notes/:note_id
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a project |
| `merge_request_id` | integer | yes | The ID of a merge request |
| `note_id` | integer | yes | The ID of a note |

```bash
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/7/notes/1602
```

Example Response:

```json
{
  "id": 1602,
  "body": "This is a good idea.",
  "attachment": null,
  "author": {
    "id": 1,
    "username": "pipin",
    "email": "admin@example.com",
    "name": "Pip",
    "state": "active",
    "created_at": "2013-09-30T13:46:01Z",
    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/u/pipin"
  },
  "created_at": "2016-04-05T22:11:59.923Z",
  "system": false,
  "noteable_id": 7,
  "noteable_type": "MergeRequest",
  "upvote": false,
  "downvote": false
}
```