- Snippet visibility level
- List all snippets for a user
- Get a single snippet
- Single snippet contents
- Create new snippet
- Update snippet
- Delete snippet
- List all public snippets
- Get user agent details
Snippets API
Introduced in GitLab 8.15.
Snippets API operates on snippets.
Snippet visibility level
Snippets in GitLab can be either private, internal, or public.
You can set it with the visibility
field in the snippet.
Valid values for snippet visibility levels are:
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. |
List all snippets for a user
Get a list of the current user’s snippets.
GET /snippets
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets
Example response:
[
{
"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"
}
]
Get a single snippet
Get a single snippet.
GET /snippets/:id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | ID of snippet to retrieve. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1
Example response:
{
"id": 1,
"title": "test",
"file_name": "add.rb",
"description": "Ruby test snippet",
"visibility": "private",
"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",
}
Single snippet contents
Get a single snippet’s raw contents.
GET /snippets/:id/raw
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | ID of snippet to retrieve. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/raw
Example response:
Hello World snippet
Create new snippet
Create a new snippet.
POST /snippets
Parameters:
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. |
Example request:
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
Example response:
{
"id": 1,
"title": "This is a snippet",
"file_name": "test.txt",
"description": "Hello World snippet",
"visibility": "internal",
"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
Update an existing snippet.
PUT /snippets/:id
Parameters:
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. |
Example request:
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
Example response:
{
"id": 1,
"title": "test",
"file_name": "add.rb",
"description": "description of snippet",
"visibility": "internal",
"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
Delete an existing snippet.
DELETE /snippets/:id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | ID of snippet to delete. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1"
The following are possible return codes:
Code | Description |
---|---|
204
| Delete was successful. No data is returned. |
404
| The snippet wasn’t found. |
List all public snippets
List all public snippets.
GET /snippets/public
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
per_page
| integer | no | Number of snippets to return per page. |
page
| integer | no | Page to retrieve. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1
Example response:
[
{
"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",
"web_url": "http://localhost:3000/snippets/48",
"visibility": "public"
}
]
Get user agent details
Introduced in GitLab 9.4.
GET /snippets/:id/user_agent_detail
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | ID of snippet. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/user_agent_detail
Example response:
{
"user_agent": "AppleWebKit/537.36",
"ip_address": "127.0.0.1",
"akismet_submitted": false
}
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc