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:

VisibilityDescription
privateSnippet is visible only to the snippet creator.
internalSnippet is visible for any logged in user.
publicSnippet 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:

AttributeTypeRequiredDescription
idintegeryesID 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:

AttributeTypeRequiredDescription
idintegeryesID 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.

Note: The user must have permission to create new snippets.
POST /snippets

Parameters:

AttributeTypeRequiredDescription
titlestringyesTitle of a snippet.
file_namestringyesName of a snippet file.
contentstringyesContent of a snippet.
descriptionstringnoDescription of a snippet.
visibilitystringnoSnippet’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.

Note: The user must have permission to change an existing snippet.
PUT /snippets/:id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of snippet to update.
titlestringnoTitle of a snippet.
file_namestringnoName of a snippet file.
descriptionstringnoDescription of a snippet.
contentstringnoContent of a snippet.
visibilitystringnoSnippet’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:

AttributeTypeRequiredDescription
idintegeryesID 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:

CodeDescription
204Delete was successful. No data is returned.
404The snippet wasn’t found.

List all public snippets

List all public snippets.

GET /snippets/public

Parameters:

AttributeTypeRequiredDescription
per_pageintegernoNumber of snippets to return per page.
pageintegernoPage 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.

Note: Available only for administrators.
GET /snippets/:id/user_agent_detail
AttributeTypeRequiredDescription
idintegeryesID of snippet.

Example request:

curl --request GET --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
}