Snippets API

Snippets API operates on snippets. Related APIs exist for project snippets and moving snippets between storages.

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 authenticated user except external users.
publicSnippet can be accessed without any authentication.

List all snippets for current user

Get a list of the current user’s snippets.

GET /snippets

Parameters:

AttributeTypeRequiredDescription
per_pageintegernoNumber of snippets to return per page.
pageintegernoPage to retrieve.
created_afterdatetimenoReturn snippets created after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z)
created_beforedatetimenoReturn snippets created before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z)

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://example.com/user0"
        },
        "updated_at": "2018-09-18T01:12:26.383Z",
        "created_at": "2018-09-18T01:12:26.383Z",
        "project_id": null,
        "web_url": "http://example.com/snippets/42",
        "raw_url": "http://example.com/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://example.com/user0"
        },
        "updated_at": "2018-09-18T01:12:26.360Z",
        "created_at": "2018-09-18T01:12:26.360Z",
        "project_id": 1,
        "web_url": "http://example.com/gitlab-org/gitlab-test/snippets/41",
        "raw_url": "http://example.com/gitlab-org/gitlab-test/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",
  "project_id": null,
  "web_url": "http://example.com/snippets/1",
  "raw_url": "http://example.com/snippets/1/raw"
}

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

Snippet repository file content

Returns the raw file content as plain text.

GET /snippets/:id/files/:ref/:file_path/raw

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of snippet to retrieve.
refstringyesReference to a tag, branch or commit.
file_pathstringyesURL-encoded path to the file.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1/files/main/snippet%2Erb/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_namestringnoDeprecated: Use files instead. Name of a snippet file
contentstringnoDeprecated: Use files instead. Content of a snippet
descriptionstringnoDescription of a snippet
visibilitystringnoSnippet’s visibility
filesarray of hashesnoAn array of snippet files
files:file_pathstringyesFile path of the snippet file
files:contentstringyesContent of the snippet file

Example request:

curl --request POST "https://gitlab.example.com/api/v4/snippets" \
     --header 'Content-Type: application/json' \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     -d @snippet.json

snippet.json used in the above example request:

{
  "title": "This is a snippet",
  "description": "Hello World snippet",
  "visibility": "internal",
  "files": [
    {
      "content": "Hello world",
      "file_path": "test.txt"
    }
  ]
}

Example response:

{
  "id": 1,
  "title": "This is a snippet",
  "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",
  "project_id": null,
  "web_url": "http://example.com/snippets/1",
  "raw_url": "http://example.com/snippets/1/raw",
  "ssh_url_to_repo": "ssh://git@gitlab.example.com:snippets/1.git",
  "http_url_to_repo": "https://gitlab.example.com/snippets/1.git",
  "file_name": "test.txt",
  "files": [
    {
      "path": "text.txt",
      "raw_url": "https://gitlab.example.com/-/snippets/1/raw/main/renamed.md"
    }
  ]
}

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_namestringnoDeprecated: Use files instead. Name of a snippet file
contentstringnoDeprecated: Use files instead. Content of a snippet
descriptionstringnoDescription of a snippet
visibilitystringnoSnippet’s visibility
filesarray of hashessometimesAn array of snippet files. Required when updating snippets with multiple files.
files:actionstringyesType of action to perform on the file, one of: create, update, delete, move
files:file_pathstringnoFile path of the snippet file
files:previous_pathstringnoPrevious path of the snippet file
files:contentstringnoContent of the snippet file

Example request:

curl --request PUT "https://gitlab.example.com/api/v4/snippets/1" \
     --header 'Content-Type: application/json' \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     -d @snippet.json

snippet.json used in the above example request:

{
  "title": "foo",
  "files": [
    {
      "action": "move",
      "previous_path": "test.txt",
      "file_path": "renamed.md"
    }
  ]
}

Example response:

{
  "id": 1,
  "title": "test",
  "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",
  "project_id": null,
  "web_url": "http://example.com/snippets/1",
  "raw_url": "http://example.com/snippets/1/raw",
  "ssh_url_to_repo": "ssh://git@gitlab.example.com:snippets/1.git",
  "http_url_to_repo": "https://gitlab.example.com/snippets/1.git",
  "file_name": "renamed.md",
  "files": [
    {
      "path": "renamed.md",
      "raw_url": "https://gitlab.example.com/-/snippets/1/raw/main/renamed.md"
    }
  ]
}

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.
created_afterdatetimenoReturn snippets created after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z)
created_beforedatetimenoReturn snippets created before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z)

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://example.com/elton_wehner"
        },
        "created_at": "2016-11-25T16:53:34.504Z",
        "file_name": "oconnerrice.rb",
        "id": 49,
        "title": "Ratione cupiditate et laborum temporibus.",
        "updated_at": "2016-11-25T16:53:34.504Z",
        "project_id": null,
        "web_url": "http://example.com/snippets/49",
        "raw_url": "http://example.com/snippets/49/raw"
    },
    {
        "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://example.com/adaline"
        },
        "created_at": "2016-11-25T16:53:34.479Z",
        "file_name": "muellershields.rb",
        "id": 48,
        "title": "Minus similique nesciunt vel fugiat qui ullam sunt.",
        "updated_at": "2016-11-25T16:53:34.479Z",
        "project_id": null,
        "web_url": "http://example.com/snippets/48",
        "raw_url": "http://example.com/snippets/49/raw",
        "visibility": "public"
    }
]

List all snippets

Introduced in GitLab 16.3.

List all snippets the current user has access to. Users with the Administrator or Auditor access levels can see all snippets (both personal and project).

GET /snippets/all

Parameters:

AttributeTypeRequiredDescription
created_afterdatetimenoReturn snippets created after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
created_beforedatetimenoReturn snippets created before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
pageintegernoPage to retrieve.
per_pageintegernoNumber of snippets to return per page.
repository_storagestringnoFilter by repository storage used by the snippet (administrators only). Introduced in GitLab 16.3

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/all?per_page=2&page=1"

Example response:

[
  {
    "id": 113,
    "title": "Internal Project Snippet",
    "description": null,
    "visibility": "internal",
    "author": {
      "id": 17,
      "username": "tim_kreiger",
      "name": "Tim Kreiger",
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",
      "web_url": "http://example.com/tim_kreiger"
    },
    "created_at": "2023-08-03T10:21:02.480Z",
    "updated_at": "2023-08-03T10:21:02.480Z",
    "project_id": 35,
    "web_url": "http://example.com/tim_kreiger/internal_project/-/snippets/113",
    "raw_url": "http://example.com/tim_kreiger/internal_project/-/snippets/113/raw",
    "file_name": "",
    "files": [],
    "repository_storage": "default"
  },
  {
    "id": 112,
    "title": "Private Personal Snippet",
    "description": null,
    "visibility": "private",
    "author": {
      "id": 1,
      "username": "root",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",
      "web_url": "http://example.com/root"
    },
    "created_at": "2023-08-03T10:20:59.994Z",
    "updated_at": "2023-08-03T10:20:59.994Z",
    "project_id": null,
    "web_url": "http://example.com/-/snippets/112",
    "raw_url": "http://example.com/-/snippets/112/raw",
    "file_name": "",
    "files": [],
    "repository_storage": "default"
  },
  {
    "id": 111,
    "title": "Public Personal Snippet",
    "description": null,
    "visibility": "public",
    "author": {
      "id": 17,
      "username": "tim_kreiger",
      "name": "Tim Kreiger",
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",
      "web_url": "http://example.com/tim_kreiger"
    },
    "created_at": "2023-08-03T10:21:01.312Z",
    "updated_at": "2023-08-03T10:21:01.312Z",
    "project_id": null,
    "web_url": "http://example.com/-/snippets/111",
    "raw_url": "http://example.com/-/snippets/111/raw",
    "file_name": "",
    "files": [],
    "repository_storage": "default"
  },
]

Get user agent details

note
Available only for administrators.
GET /snippets/:id/user_agent_detail
AttributeTypeRequiredDescription
idintegeryesID 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
}