notes.md 11.1 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 18 19 20 21
| Attribute           | Type             | Required   | Description                                                                                                                                         |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
| `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 42
    "noteable_type": "Issue",
    "noteable_iid": 377
43 44
  },
  {
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
45 46 47 48 49 50 51 52 53 54
    "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"
55
    },
56
    "created_at": "2013-10-02T09:56:03Z",
57
    "updated_at": "2013-10-02T09:56:03Z",
58
    "system": true,
59
    "noteable_id": 121,
sue445's avatar
sue445 committed
60 61
    "noteable_type": "Issue",
    "noteable_iid": 121
62 63 64
  }
]
```
65 66 67 68

### Get single issue note

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

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

Parameters:

76
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
77
- `issue_iid` (required) - The IID of a project issue
Ciro Santilli's avatar
Ciro Santilli committed
78
- `note_id` (required) - The ID of an issue note
Nihad Abbasov's avatar
Nihad Abbasov committed
79

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

82 83
Creates a new note to a single project issue. If you create a note where the body
only contains an Award Emoji, you'll receive this object back.
Nihad Abbasov's avatar
Nihad Abbasov committed
84 85

```
86
POST /projects/:id/issues/:issue_iid/notes
Nihad Abbasov's avatar
Nihad Abbasov committed
87 88 89 90
```

Parameters:

91
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
92
- `issue_id` (required) - The IID of an issue
Ciro Santilli's avatar
Ciro Santilli committed
93
- `body` (required) - The content of a note
94
- `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z
95

96 97 98 99 100
### Modify existing issue note

Modify existing note of an issue.

```
101
PUT /projects/:id/issues/:issue_iid/notes/:note_id
102 103 104 105
```

Parameters:

106
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
107
- `issue_iid` (required) - The IID of an issue
108 109 110
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note

Robert Schilling's avatar
Robert Schilling committed
111
### Delete an issue note
Robert Schilling's avatar
Robert Schilling committed
112

113
Deletes an existing note of an issue.
Robert Schilling's avatar
Robert Schilling committed
114 115

```
116
DELETE /projects/:id/issues/:issue_iid/notes/:note_id
Robert Schilling's avatar
Robert Schilling committed
117 118 119 120
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
121 122
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
123
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
124
| `issue_iid` | integer | yes | The IID of an issue |
Robert Schilling's avatar
Robert Schilling committed
125 126 127
| `note_id` | integer | yes | The ID of a note |

```bash
128
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636
Robert Schilling's avatar
Robert Schilling committed
129 130
```

131 132 133 134 135
## 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
136 137

```
138
GET /projects/:id/snippets/:snippet_id/notes
139
GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at
Nihad Abbasov's avatar
Nihad Abbasov committed
140 141
```

142 143 144 145 146 147
| Attribute           | Type             | Required   | Description                                                                                                                                         |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
| `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
148

149
### Get single snippet note
Nihad Abbasov's avatar
Nihad Abbasov committed
150

151
Returns a single note for a given snippet.
Nihad Abbasov's avatar
Nihad Abbasov committed
152 153

```
154
GET /projects/:id/snippets/:snippet_id/notes/:note_id
Nihad Abbasov's avatar
Nihad Abbasov committed
155 156 157 158
```

Parameters:

159
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
Ciro Santilli's avatar
Ciro Santilli committed
160
- `snippet_id` (required) - The ID of a project snippet
Ville Skyttä's avatar
Ville Skyttä committed
161
- `note_id` (required) - The ID of a snippet note
Nihad Abbasov's avatar
Nihad Abbasov committed
162

163 164
```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
165 166 167 168 169 170 171 172 173 174
  "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"
175
  },
176
  "expires_at": null,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
177 178
  "updated_at": "2013-10-02T07:34:20Z",
  "created_at": "2013-10-02T07:34:20Z"
179 180
}
```
181 182 183 184

### Create new snippet note

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

```
188
POST /projects/:id/snippets/:snippet_id/notes
189 190 191 192
```

Parameters:

193
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
194 195 196 197 198 199 200 201 202 203 204 205 206
- `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:

207
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
208 209
- `snippet_id` (required) - The ID of a snippet
- `note_id` (required) - The ID of a note
Ciro Santilli's avatar
Ciro Santilli committed
210
- `body` (required) - The content of a note
211

Robert Schilling's avatar
Robert Schilling committed
212
### Delete a snippet note
Robert Schilling's avatar
Robert Schilling committed
213

214
Deletes an existing note of a snippet.
Robert Schilling's avatar
Robert Schilling committed
215 216 217 218 219 220 221

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

Parameters:

Robert Schilling's avatar
Robert Schilling committed
222 223
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
224
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
Robert Schilling's avatar
Robert Schilling committed
225 226 227 228
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a note |

```bash
229
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659
Robert Schilling's avatar
Robert Schilling committed
230 231
```

232 233 234 235 236
## 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
237 238

```
239
GET /projects/:id/merge_requests/:merge_request_iid/notes
240
GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=updated_at
Nihad Abbasov's avatar
Nihad Abbasov committed
241 242
```

243 244 245 246 247 248
| Attribute           | Type             | Required   | Description                                                                                                                                         |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
| `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
249

250 251 252
### Get single merge request note

Returns a single note for a given merge request.
Nihad Abbasov's avatar
Nihad Abbasov committed
253 254

```
255
GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
Nihad Abbasov's avatar
Nihad Abbasov committed
256 257 258 259
```

Parameters:

260
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
261
- `merge_request_iid` (required) - The IID of a project merge request
Ciro Santilli's avatar
Ciro Santilli committed
262
- `note_id` (required) - The ID of a merge request note
263

264 265
```json
{
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
266 267 268 269 270 271 272 273 274 275
  "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"
276
  },
277
  "created_at": "2013-10-02T08:57:14Z",
278
  "updated_at": "2013-10-02T08:57:14Z",
279 280
  "system": false,
  "noteable_id": 2,
sue445's avatar
sue445 committed
281 282
  "noteable_type": "MergeRequest",
  "noteable_iid": 2
283 284
}
```
285 286 287 288

### Create new merge request note

Creates a new note for a single merge request.
289 290
If you create a note where the body only contains an Award Emoji, you'll receive
this object back.
291 292

```
293
POST /projects/:id/merge_requests/:merge_request_iid/notes
294 295 296 297
```

Parameters:

298
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
299
- `merge_request_iid` (required) - The IID of a merge request
Ciro Santilli's avatar
Ciro Santilli committed
300
- `body` (required) - The content of a note
301 302 303 304 305 306

### Modify existing merge request note

Modify existing note of a merge request.

```
307
PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
308 309 310 311
```

Parameters:

312
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
313
- `merge_request_iid` (required) - The IID of a merge request
314 315
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note
Robert Schilling's avatar
Robert Schilling committed
316

Robert Schilling's avatar
Robert Schilling committed
317
### Delete a merge request note
Robert Schilling's avatar
Robert Schilling committed
318

319
Deletes an existing note of a merge request.
Robert Schilling's avatar
Robert Schilling committed
320 321

```
322
DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
Robert Schilling's avatar
Robert Schilling committed
323 324 325 326
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
327 328
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
329
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
330
| `merge_request_iid` | integer | yes | The IID of a merge request |
Robert Schilling's avatar
Robert Schilling committed
331 332 333
| `note_id` | integer | yes | The ID of a note |

```bash
334
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602
Robert Schilling's avatar
Robert Schilling committed
335
```