snippets.md 10.3 KB
Newer Older
1
# Snippets API
2

3
4
5
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373) in GitLab 8.15.

Snippets API operates on [snippets](../user/snippets.md).
6

7
## Snippet visibility level
8
9

Snippets in GitLab can be either private, internal, or public.
10
You can set it with the `visibility` field in the snippet.
11

12
Valid values for snippet visibility levels are:
13

14
15
16
17
18
| Visibility | Description                                         |
|:-----------|:----------------------------------------------------|
| `private`  | Snippet is visible only to the snippet creator.     |
| `internal` | Snippet is visible for any logged in user.          |
| `public`   | Snippet can be accessed without any authentication. |
19

20
## List all snippets for a user
21

22
Get a list of the current user's snippets.
23

24
```text
25
26
27
GET /snippets
```

28
Example request:
29

30
31
32
33
34
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets
```

Example response:
35

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
```json
[
    {
        "id": 42,
        "title": "Voluptatem iure ut qui aut et consequatur quaerat.",
        "file_name": "mclaughlin.rb",
        "description": null,
        "visibility": "internal",
        "author": {
            "id": 22,
            "name": "User 0",
            "username": "user0",
            "state": "active",
            "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",
            "web_url": "http://localhost:3000/user0"
        },
        "updated_at": "2018-09-18T01:12:26.383Z",
        "created_at": "2018-09-18T01:12:26.383Z",
        "project_id": null,
        "web_url": "http://localhost:3000/snippets/42",
        "raw_url": "http://localhost:3000/snippets/42/raw"
    },
    {
        "id": 41,
        "title": "Ut praesentium non et atque.",
        "file_name": "ondrickaemard.rb",
        "description": null,
        "visibility": "internal",
        "author": {
            "id": 22,
            "name": "User 0",
            "username": "user0",
            "state": "active",
            "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",
            "web_url": "http://localhost:3000/user0"
        },
        "updated_at": "2018-09-18T01:12:26.360Z",
        "created_at": "2018-09-18T01:12:26.360Z",
        "project_id": null,
        "web_url": "http://localhost:3000/snippets/41",
        "raw_url": "http://localhost:3000/snippets/41/raw"
    }
]
79
```
80
81
82
83
84
85

## Get a single snippet

Get a single snippet.

```text
86
87
88
89
90
GET /snippets/:id
```

Parameters:

91
92
93
94
95
| Attribute | Type    | Required | Description                |
|:----------|:--------|:---------|:---------------------------|
| `id`      | integer | yes      | ID of snippet to retrieve. |

Example request:
96

97
```sh
98
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1
99
100
101
102
```

Example response:

103
```json
104
105
106
107
{
  "id": 1,
  "title": "test",
  "file_name": "add.rb",
108
  "description": "Ruby test snippet",
109
  "visibility": "private",
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
  "author": {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "created_at": "2012-05-23T08:00:58Z"
  },
  "expires_at": null,
  "updated_at": "2012-06-28T10:52:04Z",
  "created_at": "2012-06-28T10:52:04Z",
  "web_url": "http://example.com/snippets/1",
}
```

125
126
127
128
## Single snippet contents

Get a single snippet's raw contents.

129
```text
130
131
132
133
134
GET /snippets/:id/raw
```

Parameters:

135
136
137
| Attribute | Type    | Required | Description                |
|:----------|:--------|:---------|:---------------------------|
| `id`      | integer | yes      | ID of snippet to retrieve. |
138

139
140
141
Example request:

```sh
142
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/raw
143
144
145
146
```

Example response:

147
```text
148
149
150
Hello World snippet
```

151
152
## Create new snippet

153
Create a new snippet.
154

155
156
157
158
NOTE: **Note:**
The user must have permission to create new snippets.

```text
159
160
161
162
163
POST /snippets
```

Parameters:

164
165
166
167
168
169
170
| Attribute     | Type   | Required | Description                                        |
|:--------------|:-------|:---------|:---------------------------------------------------|
| `title`       | string | yes      | Title of a snippet.                                |
| `file_name`   | string | yes      | Name of a snippet file.                            |
| `content`     | string | yes      | Content of a snippet.                              |
| `description` | string | no       | Description of a snippet.                          |
| `visibility`  | string | no       | Snippet's [visibility](#snippet-visibility-level). |
171

172
Example request:
173

174
```sh
175
176
177
178
179
curl --request POST \
     --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \
     --header 'Content-Type: application/json' \
     --header "PRIVATE-TOKEN: valid_api_token" \
     https://gitlab.example.com/api/v4/snippets
180
181
182
183
```

Example response:

184
```json
185
186
187
188
{
  "id": 1,
  "title": "This is a snippet",
  "file_name": "test.txt",
189
  "description": "Hello World snippet",
190
  "visibility": "internal",
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
  "author": {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "created_at": "2012-05-23T08:00:58Z"
  },
  "expires_at": null,
  "updated_at": "2012-06-28T10:52:04Z",
  "created_at": "2012-06-28T10:52:04Z",
  "web_url": "http://example.com/snippets/1",
}
```

## Update snippet

208
Update an existing snippet.
209

210
211
212
213
NOTE: **Note:**
The user must have permission to change an existing snippet.

```text
214
215
216
217
218
PUT /snippets/:id
```

Parameters:

219
220
221
222
223
224
225
226
| Attribute     | Type    | Required | Description                                        |
|:--------------|:--------|:---------|:---------------------------------------------------|
| `id`          | integer | yes      | ID of snippet to update.                           |
| `title`       | string  | no       | Title of a snippet.                                |
| `file_name`   | string  | no       | Name of a snippet file.                            |
| `description` | string  | no       | Description of a snippet.                          |
| `content`     | string  | no       | Content of a snippet.                              |
| `visibility`  | string  | no       | Snippet's [visibility](#snippet-visibility-level). |
227

228
Example request:
229

230
```sh
231
232
233
234
235
curl --request PUT \
     --data '{"title": "foo", "content": "bar"}' \
     --header 'Content-Type: application/json' \
     --header "PRIVATE-TOKEN: valid_api_token" \
     https://gitlab.example.com/api/v4/snippets/1
236
237
238
239
```

Example response:

240
```json
241
242
243
244
{
  "id": 1,
  "title": "test",
  "file_name": "add.rb",
245
  "description": "description of snippet",
246
  "visibility": "internal",
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
  "author": {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "created_at": "2012-05-23T08:00:58Z"
  },
  "expires_at": null,
  "updated_at": "2012-06-28T10:52:04Z",
  "created_at": "2012-06-28T10:52:04Z",
  "web_url": "http://example.com/snippets/1",
}
```

## Delete snippet

264
Delete an existing snippet.
265

266
```text
267
268
269
270
271
DELETE /snippets/:id
```

Parameters:

272
273
274
| Attribute | Type    | Required | Description              |
|:----------|:--------|:---------|:-------------------------|
| `id`      | integer | yes      | ID of snippet to delete. |
275

276
Example request:
277

278
```sh
279
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1"
280
281
```

282
The following are possible return codes:
283

284
285
286
287
| Code  | Description                                 |
|:------|:--------------------------------------------|
| `204` | Delete was successful. No data is returned. |
| `404` | The snippet wasn't found.                   |
288

289
290
291
292
293
## List all public snippets

List all public snippets.

```text
294
295
296
GET /snippets/public
```

297
298
299
300
301
302
Parameters:

| Attribute  | Type    | Required | Description                            |
|:-----------|:--------|:---------|:---------------------------------------|
| `per_page` | integer | no       | Number of snippets to return per page. |
| `page`     | integer | no       | Page to retrieve.                      |
303

304
305
306
Example request:

```sh
307
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1
308
309
310
311
```

Example response:

312
```json
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
[
    {
        "author": {
            "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",
            "id": 12,
            "name": "Libby Rolfson",
            "state": "active",
            "username": "elton_wehner",
            "web_url": "http://localhost:3000/elton_wehner"
        },
        "created_at": "2016-11-25T16:53:34.504Z",
        "file_name": "oconnerrice.rb",
        "id": 49,
        "raw_url": "http://localhost:3000/snippets/49/raw",
        "title": "Ratione cupiditate et laborum temporibus.",
        "updated_at": "2016-11-25T16:53:34.504Z",
        "web_url": "http://localhost:3000/snippets/49"
    },
    {
        "author": {
            "avatar_url": "http://www.gravatar.com/avatar/36583b28626de71061e6e5a77972c3bd?s=80&d=identicon",
            "id": 16,
            "name": "Llewellyn Flatley",
            "state": "active",
            "username": "adaline",
            "web_url": "http://localhost:3000/adaline"
        },
        "created_at": "2016-11-25T16:53:34.479Z",
        "file_name": "muellershields.rb",
        "id": 48,
        "raw_url": "http://localhost:3000/snippets/48/raw",
        "title": "Minus similique nesciunt vel fugiat qui ullam sunt.",
        "updated_at": "2016-11-25T16:53:34.479Z",
346
347
        "web_url": "http://localhost:3000/snippets/48",
        "visibility": "public"
348
349
350
    }
]
```
James Lopez's avatar
James Lopez committed
351
352
353

## Get user agent details

354
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655) in GitLab 9.4.
James Lopez's avatar
James Lopez committed
355

356
357
NOTE: **Note:**
Available only for administrators.
James Lopez's avatar
James Lopez committed
358

359
```text
James Lopez's avatar
James Lopez committed
360
361
362
GET /snippets/:id/user_agent_detail
```

363
364
365
| Attribute | Type    | Required | Description    |
|:----------|:--------|:---------|:---------------|
| `id`      | integer | yes      | ID of snippet. |
James Lopez's avatar
James Lopez committed
366

367
368
369
Example request:

```sh
370
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/user_agent_detail
James Lopez's avatar
James Lopez committed
371
372
373
374
375
376
377
378
```

Example response:

```json
{
  "user_agent": "AppleWebKit/537.36",
  "ip_address": "127.0.0.1",
James Lopez's avatar
James Lopez committed
379
  "akismet_submitted": false
James Lopez's avatar
James Lopez committed
380
381
}
```