BigW Consortium Gitlab

notes.md 8.62 KB
Newer Older
1 2
# Notes

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 38
    "noteable_id": 377,
    "noteable_type": "Issue"
39 40
  },
  {
41 42 43 44 45 46 47 48 49 50
    "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"
51
    },
52
    "created_at": "2013-10-02T09:56:03Z",
53
    "updated_at": "2013-10-02T09:56:03Z",
54
    "system": true,
55 56
    "noteable_id": 121,
    "noteable_type": "Issue"
57 58 59
  }
]
```
60 61 62 63

### Get single issue note

Returns a single note for a specific project issue
Nihad Abbasov committed
64 65

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

Parameters:

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

75
### Create new issue note
76

77 78
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.
79 80

```
81
POST /projects/:id/issues/:issue_iid/notes
82 83 84 85
```

Parameters:

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

91 92 93 94 95
### Modify existing issue note

Modify existing note of an issue.

```
96
PUT /projects/:id/issues/:issue_iid/notes/:note_id
97 98 99 100
```

Parameters:

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

106
### Delete an issue note
107

108
Deletes an existing note of an issue.
109 110

```
111
DELETE /projects/:id/issues/:issue_iid/notes/:note_id
112 113 114 115
```

Parameters:

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

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

126 127 128 129 130
## 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
131 132

```
133
GET /projects/:id/snippets/:snippet_id/notes
Nihad Abbasov committed
134 135 136 137
```

Parameters:

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

141
### Get single snippet note
Nihad Abbasov committed
142

143
Returns a single note for a given snippet.
Nihad Abbasov committed
144 145

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

Parameters:

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

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

### Create new snippet note

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

```
180
POST /projects/:id/snippets/:snippet_id/notes
181 182 183 184
```

Parameters:

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

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

204
### Delete a snippet note
205

206
Deletes an existing note of a snippet.
207 208 209 210 211 212 213

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

Parameters:

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

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

224 225 226 227 228
## Merge Requests

### List all merge request notes

Gets a list of all notes for a single merge request.
Nihad Abbasov committed
229 230

```
231
GET /projects/:id/merge_requests/:merge_request_iid/notes
Nihad Abbasov committed
232 233 234 235
```

Parameters:

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

239 240 241
### Get single merge request note

Returns a single note for a given merge request.
Nihad Abbasov committed
242 243

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

Parameters:

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

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

### Create new merge request note

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

```
281
POST /projects/:id/merge_requests/:merge_request_iid/notes
282 283 284 285
```

Parameters:

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

### Modify existing merge request note

Modify existing note of a merge request.

```
295
PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
296 297 298 299
```

Parameters:

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

305
### Delete a merge request note
306

307
Deletes an existing note of a merge request.
308 309

```
310
DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
311 312 313 314
```

Parameters:

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

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