Project snippets

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to manage project snippets. Related APIs exist for personal snippets and moving snippets between storages.

List snippets

Get a list of project snippets.

GET /projects/:id/snippets

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.

If successful, returns 200 OK and the following response attributes:

Attribute Type Description
author.created_at string Date and time when the author account was created.
author.email string Email address of the snippet author.
author.id integer ID of the snippet author.
author.name string Display name of the snippet author.
author.state string State of the author account.
author.username string Username of the snippet author.
created_at string Date and time when the snippet was created in ISO 8601 format.
description string Description of the snippet.
file_name string Name of the snippet file.
id integer ID of the snippet.
imported boolean If true, the snippet was imported.
imported_from string Source of the import if the snippet was imported.
project_id integer ID of the project containing the snippet.
raw_url string Direct URL to the raw snippet content.
title string Title of the snippet.
updated_at string Date and time when the snippet was last updated in ISO 8601 format.
web_url string URL to view the snippet in the GitLab web interface.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/snippets"

Example response:

[
  {
    "id": 1,
    "title": "test",
    "file_name": "add.rb",
    "description": "Ruby test snippet",
    "author": {
      "id": 1,
      "username": "john_smith",
      "email": "john@example.com",
      "name": "John Smith",
      "state": "active",
      "created_at": "2012-05-23T08:00:58Z"
    },
    "updated_at": "2012-06-28T10:52:04Z",
    "created_at": "2012-06-28T10:52:04Z",
    "imported": false,
    "imported_from": "none",
    "project_id": 1,
    "web_url": "http://example.com/example/example/snippets/1",
    "raw_url": "http://example.com/example/example/snippets/1/raw"
  },
  {
    "id": 3,
    "title": "Configuration helper",
    "file_name": "config.yml",
    "description": "YAML configuration snippet",
    "author": {
      "id": 2,
      "username": "jane_doe",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "state": "active",
      "created_at": "2013-02-15T10:30:20Z"
    },
    "updated_at": "2013-03-10T14:15:30Z",
    "created_at": "2013-03-01T09:45:12Z",
    "imported": false,
    "imported_from": "none",
    "project_id": 1,
    "web_url": "http://example.com/example/example/snippets/3",
    "raw_url": "http://example.com/example/example/snippets/3/raw"
  }
]

Get single snippet

Get a single project snippet.

GET /projects/:id/snippets/:snippet_id

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
snippet_id integer Yes ID of a project's snippet.

If successful, returns 200 OK and the following response attributes:

Attribute Type Description
author.created_at string Date and time when the author account was created.
author.email string Email address of the snippet author.
author.id integer ID of the snippet author.
author.name string Display name of the snippet author.
author.state string State of the author account.
author.username string Username of the snippet author.
created_at string Date and time when the snippet was created in ISO 8601 format.
description string Description of the snippet.
file_name string Name of the snippet file.
id integer ID of the snippet.
imported boolean If true, the snippet was imported.
imported_from string Source of the import if the snippet was imported.
project_id integer ID of the project containing the snippet.
raw_url string Direct URL to the raw snippet content.
title string Title of the snippet.
updated_at string Date and time when the snippet was last updated in ISO 8601 format.
web_url string URL to view the snippet in the GitLab web interface.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/snippets/2"

Example response:

{
  "id": 2,
  "title": "test",
  "file_name": "add.rb",
  "description": "Ruby test snippet",
  "author": {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "created_at": "2012-05-23T08:00:58Z"
  },
  "updated_at": "2012-06-28T10:52:04Z",
  "created_at": "2012-06-28T10:52:04Z",
  "imported": false,
  "imported_from": "none",
  "project_id": 1,
  "web_url": "http://example.com/example/example/snippets/2",
  "raw_url": "http://example.com/example/example/snippets/2/raw"
}

Create new snippet

Creates a new project snippet. The user must have permission to create new snippets.

POST /projects/:id/snippets

Supported attributes:

Attribute Type Required Description
files array of hashes Yes An array of snippet files.
files:content string Yes Content of the snippet file.
files:file_path string Yes File path of the snippet file.
id integer or string Yes ID or URL-encoded path of the project.
title string Yes Title of a snippet.
content string No Deprecated: Use files instead. Content of a snippet.
description string No Description of a snippet.
file_name string No Deprecated: Use files instead. Name of a snippet file.
visibility string No Visibility level for the snippet. Possible values: public, private, and internal. On GitLab.com, the internal value is not available.

If successful, returns 201 Created and the following response attributes:

Attribute Type Description
author.created_at string Date and time when the author account was created.
author.email string Email address of the snippet author.
author.id integer ID of the snippet author.
author.name string Display name of the snippet author.
author.state string State of the author account.
author.username string Username of the snippet author.
created_at string Date and time when the snippet was created in ISO 8601 format.
description string Description of the snippet.
file_name string Name of the snippet file.
id integer ID of the snippet.
imported boolean If true, the snippet was imported.
imported_from string Source of the import if the snippet was imported.
project_id integer ID of the project containing the snippet.
raw_url string Direct URL to the raw snippet content.
title string Title of the snippet.
updated_at string Date and time when the snippet was last updated in ISO 8601 format.
web_url string URL to view the snippet in the GitLab web interface.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"title": "Example Snippet Title", "description": "More verbose snippet description", "visibility": "private", "files": [{"file_path": "example.txt", "content": "source code \n with multiple lines\n"}]}' \
  --url "https://gitlab.example.com/api/v4/projects/1/snippets"

Example response:

{
  "id": 1,
  "title": "Example Snippet Title",
  "file_name": "example.txt",
  "description": "More verbose snippet description",
  "author": {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "created_at": "2012-05-23T08:00:58Z"
  },
  "updated_at": "2012-06-28T10:52:04Z",
  "created_at": "2012-06-28T10:52:04Z",
  "imported": false,
  "imported_from": "none",
  "project_id": 1,
  "web_url": "http://example.com/example/example/snippets/1",
  "raw_url": "http://example.com/example/example/snippets/1/raw"
}

Update snippet

Updates an existing project snippet. The user must have permission to change an existing snippet.

Updates to snippets with multiple files must use the files attribute.

PUT /projects/:id/snippets/:snippet_id

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
snippet_id integer Yes ID of a project's snippet.
files:action string Conditionally Type of action to perform on the file. One of: create, update, delete, move. Required when using the files attribute.
content string No Deprecated: Use files instead. Content of a snippet.
description string No Description of a snippet.
file_name string No Deprecated: Use files instead. Name of a snippet file.
files array of hashes No An array of snippet files.
files:content string No Content of the snippet file.
files:file_path string No File path of the snippet file.
files:previous_path string No Previous path of the snippet file.
title string No Title of a snippet.
visibility string No Visibility level for the snippet. Possible values: public, private, and internal. On GitLab.com, the internal value is not available.

If successful, returns 200 OK and the following response attributes:

Attribute Type Description
author.created_at string Date and time when the author account was created.
author.email string Email address of the snippet author.
author.id integer ID of the snippet author.
author.name string Display name of the snippet author.
author.state string State of the author account.
author.username string Username of the snippet author.
created_at string Date and time when the snippet was created in ISO 8601 format.
description string Description of the snippet.
file_name string Name of the snippet file.
id integer ID of the snippet.
imported boolean If true, the snippet was imported.
imported_from string Source of the import if the snippet was imported.
project_id integer ID of the project containing the snippet.
raw_url string Direct URL to the raw snippet content.
title string Title of the snippet.
updated_at string Date and time when the snippet was last updated in ISO 8601 format.
web_url string URL to view the snippet in the GitLab web interface.

Example request:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"title": "Updated Snippet Title", "description": "More verbose snippet description", "visibility": "private", "files": [{"action": "update", "file_path": "example.txt", "content": "updated source code \n with multiple lines\n"}]}' \
  --url "https://gitlab.example.com/api/v4/projects/1/snippets/2"

Example response:

{
  "id": 2,
  "title": "Updated Snippet Title",
  "file_name": "example.txt",
  "description": "More verbose snippet description",
  "author": {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "created_at": "2012-05-23T08:00:58Z"
  },
  "updated_at": "2012-06-28T10:52:04Z",
  "created_at": "2012-06-28T10:52:04Z",
  "imported": false,
  "imported_from": "none",
  "project_id": 1,
  "web_url": "http://example.com/example/example/snippets/2",
  "raw_url": "http://example.com/example/example/snippets/2/raw"
}

Delete snippet

Deletes an existing project snippet. This returns a 204 No Content status code if the operation was successfully or 404 if the resource was not found.

DELETE /projects/:id/snippets/:snippet_id

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
snippet_id integer Yes ID of a project's snippet.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/snippets/2"

Snippet content

Returns the raw project snippet as plain text.

GET /projects/:id/snippets/:snippet_id/raw

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
snippet_id integer Yes ID of a project's snippet.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/snippets/2/raw"

Snippet repository file content

Returns the raw file content as plain text.

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

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
file_path string Yes URL-encoded path to the file, for example, snippet%2Erb.
ref string Yes Name of a branch, tag or commit, for example, main.
snippet_id integer Yes ID of a project's snippet.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/snippets/2/files/master/snippet%2Erb/raw"

Get user agent details

Available only for users with administrator access.

GET /projects/:id/snippets/:snippet_id/user_agent_detail

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
snippet_id integer Yes ID of a snippet.

If successful, returns 200 OK and the following response attributes:

Attribute Type Description
akismet_submitted boolean If true, the snippet was submitted to Akismet for spam detection.
ip_address string IP address of the user who created the snippet.
user_agent string User agent string of the browser used to create the snippet.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/snippets/2/user_agent_detail"

Example response:

{
  "user_agent": "AppleWebKit/537.36",
  "ip_address": "127.0.0.1",
  "akismet_submitted": false
}