BigW Consortium Gitlab

notes.md 8.69 KB
Newer Older
1
# Notes API
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 committed
10 11

```
12
GET /projects/:id/issues/:issue_iid/notes
Nihad Abbasov committed
13 14 15 16
```

Parameters:

17
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
18
- `issue_iid` (required) - The IID of an issue
Nihad Abbasov committed
19

20 21 22
```json
[
  {
23
    "id": 302,
24
    "body": "closed",
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
    "system": true,
37
    "noteable_id": 377,
sue445 committed
38 39
    "noteable_type": "Issue",
    "noteable_iid": 377
40 41
  },
  {
42 43 44 45 46 47 48 49 50 51
    "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"
52
    },
53
    "created_at": "2013-10-02T09:56:03Z",
54
    "updated_at": "2013-10-02T09:56:03Z",
55
    "system": true,
56
    "noteable_id": 121,
sue445 committed
57 58
    "noteable_type": "Issue",
    "noteable_iid": 121
59 60 61
  }
]
```
62 63 64 65

### Get single issue note

Returns a single note for a specific project issue
Nihad Abbasov committed
66 67

```
68
GET /projects/:id/issues/:issue_iid/notes/:note_id
Nihad Abbasov committed
69 70 71 72
```

Parameters:

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

77
### Create new issue note
78

79 80
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.
81 82

```
83
POST /projects/:id/issues/:issue_iid/notes
84 85 86 87
```

Parameters:

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

93 94 95 96 97
### Modify existing issue note

Modify existing note of an issue.

```
98
PUT /projects/:id/issues/:issue_iid/notes/:note_id
99 100 101 102
```

Parameters:

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

108
### Delete an issue note
109

110
Deletes an existing note of an issue.
111 112

```
113
DELETE /projects/:id/issues/:issue_iid/notes/:note_id
114 115 116 117
```

Parameters:

118 119
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
120
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
121
| `issue_iid` | integer | yes | The IID of an issue |
122 123 124
| `note_id` | integer | yes | The ID of a note |

```bash
125
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636
126 127
```

128 129 130 131 132
## 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 committed
133 134

```
135
GET /projects/:id/snippets/:snippet_id/notes
Nihad Abbasov committed
136 137 138 139
```

Parameters:

140
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
Ciro Santilli committed
141
- `snippet_id` (required) - The ID of a project snippet
Nihad Abbasov committed
142

143
### Get single snippet note
Nihad Abbasov committed
144

145
Returns a single note for a given snippet.
Nihad Abbasov committed
146 147

```
148
GET /projects/:id/snippets/:snippet_id/notes/:note_id
Nihad Abbasov committed
149 150 151 152
```

Parameters:

153
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
Ciro Santilli committed
154 155
- `snippet_id` (required) - The ID of a project snippet
- `note_id` (required) - The ID of an snippet note
Nihad Abbasov committed
156

157 158
```json
{
159 160 161 162 163 164 165 166 167 168
  "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"
169
  },
170
  "expires_at": null,
171 172
  "updated_at": "2013-10-02T07:34:20Z",
  "created_at": "2013-10-02T07:34:20Z"
173 174
}
```
175 176 177 178

### Create new snippet note

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

```
182
POST /projects/:id/snippets/:snippet_id/notes
183 184 185 186
```

Parameters:

187
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
188 189 190 191 192 193 194 195 196 197 198 199 200
- `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:

201
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
202 203
- `snippet_id` (required) - The ID of a snippet
- `note_id` (required) - The ID of a note
Ciro Santilli committed
204
- `body` (required) - The content of a note
205

206
### Delete a snippet note
207

208
Deletes an existing note of a snippet.
209 210 211 212 213 214 215

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

Parameters:

216 217
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
218
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
219 220 221 222
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a note |

```bash
223
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659
224 225
```

226 227 228 229 230
## Merge Requests

### List all merge request notes

Gets a list of all notes for a single merge request.
Nihad Abbasov committed
231 232

```
233
GET /projects/:id/merge_requests/:merge_request_iid/notes
Nihad Abbasov committed
234 235 236 237
```

Parameters:

238
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
239
- `merge_request_iid` (required) - The IID of a project merge request
Nihad Abbasov committed
240

241 242 243
### Get single merge request note

Returns a single note for a given merge request.
Nihad Abbasov committed
244 245

```
246
GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
Nihad Abbasov committed
247 248 249 250
```

Parameters:

251
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
252
- `merge_request_iid` (required) - The IID of a project merge request
Ciro Santilli committed
253
- `note_id` (required) - The ID of a merge request note
254

255 256
```json
{
257 258 259 260 261 262 263 264 265 266
  "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"
267
  },
268
  "created_at": "2013-10-02T08:57:14Z",
269
  "updated_at": "2013-10-02T08:57:14Z",
270 271
  "system": false,
  "noteable_id": 2,
sue445 committed
272 273
  "noteable_type": "MergeRequest",
  "noteable_iid": 2
274 275
}
```
276 277 278 279

### Create new merge request note

Creates a new note for a single merge request.
280 281
If you create a note where the body only contains an Award Emoji, you'll receive
this object back.
282 283

```
284
POST /projects/:id/merge_requests/:merge_request_iid/notes
285 286 287 288
```

Parameters:

289
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
290
- `merge_request_iid` (required) - The IID of a merge request
Ciro Santilli committed
291
- `body` (required) - The content of a note
292 293 294 295 296 297

### Modify existing merge request note

Modify existing note of a merge request.

```
298
PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
299 300 301 302
```

Parameters:

303
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
304
- `merge_request_iid` (required) - The IID of a merge request
305 306
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note
307

308
### Delete a merge request note
309

310
Deletes an existing note of a merge request.
311 312

```
313
DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
314 315 316 317
```

Parameters:

318 319
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
320
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
321
| `merge_request_iid` | integer | yes | The IID of a merge request |
322 323 324
| `note_id` | integer | yes | The ID of a note |

```bash
325
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602
326
```