Snippets

Use this API to manage personal and project snippets.

To move snippets between storages, use the snippet repository storage moves API.

List all snippets for a project

GET /api/v4/projects/{id}/snippets

Lists all snippets for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesProjectSnippet
`400`	Bad Request	—
`404`	Not found	—

Create a project snippet

POST /api/v4/projects/{id}/snippets

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

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`content`	String	The content of a snippet. Mutually exclusive with `files`. Exactly one of `files`, `content` must be provided
`description`	String	Description of the snippet
`file_name` Required	String	The name of a snippet file
`files`	Array of objects	Array of files for the snippet. Mutually exclusive with `content`. Exactly one of `files`, `content` must be provided
`files[].content` Required	String	Content of the snippet file
`files[].file_path` Required	String	Path of the snippet file
`title` Required	String	Title of the snippet
`visibility` Required	String	Visibility level for the snippet. On GitLab.com, the `internal` value is not available Allowed values: `private`, `internal`, `public` Minimum length: `1`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesProjectSnippet
`400`	Validation error	—
`404`	Not found	—
`422`	Unprocessable entity	—

Retrieve a project snippet

GET /api/v4/projects/{id}/snippets/{snippet_id}

Retrieves a specified project snippet.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectSnippet
`400`	Bad Request	—
`404`	Not found	—

Update a project snippet

PUT /api/v4/projects/{id}/snippets/{snippet_id}

Updates a specified project snippet. The user must have permission to modify snippets. Updates to snippets with multiple files must use the files attribute.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	ID of the snippet

Request body (application/json)

Property	Type	Description
`content`	String	Content of the snippet. Deprecated. Use `files` instead. Mutually exclusive with `files`. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`description`	String	Description of the snippet. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`file_name`	String	Name of the snippet file. Deprecated. Use `files` instead. Mutually exclusive with `files`. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`files`	Array of objects	Array of files to update for the snippet. Required when the snippet has multiple files. Mutually exclusive with `content`, `file_name`. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`files[].action` Required	String	The type of action to perform on the file, must be one of: create, update, delete, move Allowed values: `create`, `update`, `delete`, `move` Minimum length: `1`
`files[].content`	String	Content of the snippet file
`files[].file_path`	String	Path of the snippet file
`files[].previous_path`	String	Previous path of the snippet file
`title`	String	Title of the snippet. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`visibility`	String	Visibility level for the snippet. On GitLab.com, the `internal` value is not available. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided Allowed values: `private`, `internal`, `public`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectSnippet
`400`	Validation error	—
`404`	Not found	—
`422`	Unprocessable entity	—

Delete a project snippet

DELETE /api/v4/projects/{id}/snippets/{snippet_id}

Deletes a specified project snippet.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Validation error	—
`404`	Not found	—

Retrieve snippet repository file content

GET /api/v4/projects/{id}/snippets/{snippet_id}/files/{ref}/{file_path}/raw

Retrieves the raw file content from a snippet repository as plain text.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`ref` Path, required	String	The name of branch, tag or commit
`file_path` Path, required	String	The URL-encoded path to the file, like lib%2Fclass%2Erb
`snippet_id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectSnippet
`400`	Bad Request	—
`404`	Not found	—

Retrieve a raw project snippet

GET /api/v4/projects/{id}/snippets/{snippet_id}/raw

Retrieves the raw contents of a specified project snippet as plain text

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectSnippet
`400`	Bad Request	—
`404`	Not found	—

Retrieve user agent details for a project snippet

GET /api/v4/projects/{id}/snippets/{snippet_id}/user_agent_detail

Retrieves user agent details for a specified snippet. Available only for administrators.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	APIEntitiesUserAgentDetail
`400`	Bad Request	—
`404`	Not found	—

List all snippets for current user

GET /api/v4/snippets

Lists all snippets for the currently authenticated user.

Parameters

Name	Type	Description
`created_after` Query	String (date-time)	Return snippets created on or after the specified time
`created_before` Query	String (date-time)	Return snippets created on or before the specified time
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesSnippet
`400`	Bad Request	—
`404`	Not found	—

Create a snippet

POST /api/v4/snippets

Creates a snippet.

Request body (application/json)

Property	Type	Description
`content`	String	The content of a snippet. Mutually exclusive with `files`. Exactly one of `files`, `content` must be provided
`description`	String	Description of the snippet
`file_name` Required	String	The name of a snippet file
`files`	Array of objects	Array of files for the snippet. Mutually exclusive with `content`. Exactly one of `files`, `content` must be provided
`files[].content` Required	String	Content of the snippet file
`files[].file_path` Required	String	Path of the snippet file
`title` Required	String	Title of the snippet
`visibility`	String	Visibility level for the snippet. On GitLab.com, the `internal` value is not available Allowed values: `private`, `internal`, `public` Default: `internal`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalSnippet
`400`	Validation error	—
`404`	Not found	—
`422`	Unprocessable entity	—

List all snippets

GET /api/v4/snippets/all

Lists all snippets available to the currently authenticated user. Users with Administrator or Auditor access levels can see all snippets (both personal and project). This feature was introduced in GitLab 16.3.

Parameters

Name	Type	Description
`created_after` Query	String (date-time)	Return snippets created on or after the specified time
`created_before` Query	String (date-time)	Return snippets created on or before the specified time
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesSnippet
`400`	Bad Request	—
`404`	Not found	—

List all public snippets

GET /api/v4/snippets/public

Lists all public snippets accessible to the currently authenticated user.

Parameters

Name	Type	Description
`created_after` Query	String (date-time)	Return snippets created on or after the specified time
`created_before` Query	String (date-time)	Return snippets created on or before the specified time
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesPersonalSnippet
`400`	Bad Request	—
`404`	Not found	—

Retrieve a snippet

GET /api/v4/snippets/{id}

Retrieves a specified snippet.

Parameters

Name	Type	Description
`id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalSnippet
`400`	Bad Request	—
`404`	Not found	—

Update snippet

PUT /api/v4/snippets/{id}

Updates a specified snippet.

Parameters

Name	Type	Description
`id` Path, required	Integer	ID of the snippet

Request body (application/json)

Property	Type	Description
`content`	String	The content of a snippet. Mutually exclusive with `files`. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`description`	String	Description of the snippet. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`file_name`	String	The name of a snippet file. Mutually exclusive with `files`. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`files`	Array of objects	Array of files to update for the snippet. Required when the snippet has multiple files. Mutually exclusive with `content`, `file_name`. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`files[].action` Required	String	The type of action to perform on the file, must be one of: create, update, delete, move Allowed values: `create`, `update`, `delete`, `move` Minimum length: `1`
`files[].content`	String	Content of the snippet file
`files[].file_path`	String	Path of the snippet file
`files[].previous_path`	String	Previous path of the snippet file
`title`	String	Title of the snippet. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided
`visibility`	String	Visibility level for the snippet. On GitLab.com, the `internal` value is not available. At least one of `content`, `description`, `files`, `file_name`, `title`, `visibility` must be provided Allowed values: `private`, `internal`, `public`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalSnippet
`400`	Validation error	—
`404`	Not found	—
`422`	Unprocessable entity	—

Delete snippet

DELETE /api/v4/snippets/{id}

Deletes a specified snippet.

Parameters

Name	Type	Description
`id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalSnippet
`400`	Validation error	—
`404`	Not found	—

Retrieve snippet file content

GET /api/v4/snippets/{id}/files/{ref}/{file_path}/raw

Retrieves the raw file content from a snippet as plain text.

Parameters

Name	Type	Description
`ref` Path, required	String	The name of branch, tag or commit
`file_path` Path, required	String	The URL-encoded path to the file, like lib%2Fclass%2Erb
`id` Path, required	String	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not found	—

Retrieve a raw snippet

GET /api/v4/snippets/{id}/raw

Retrieves the raw contents of a specified snippet as plain text

Parameters

Name	Type	Description
`id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not found	—

Retrieve user agent details for a snippet

GET /api/v4/snippets/{id}/user_agent_detail

Retrieves user agent details for a specified snippet.

Parameters

Name	Type	Description
`id` Path, required	Integer	ID of the snippet

Responses

Code	Description	Schema
`200`	OK	APIEntitiesUserAgentDetail
`400`	Bad Request	—
`404`	Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesPersonalSnippet

Property	Type	Description
`author`	APIEntitiesUserBasic	—
`created_at`	String (date-time)	Example: `2012-06-28T10:52:04Z`
`description`	String	Example: `Ruby test snippet`
`file_name`	String	Example: `add.rb`
`files`	Array of objects	Example: `[{"path":"file.txt","raw_url":"https://gitlab.example.com/.../raw"}]`
`http_url_to_repo`	String	Example: `https://gitlab.example.com/snippets/65.git`
`id`	Integer (int64)	Example: `1`
`imported`	Boolean	Example: `false`
`imported_from`	String	Example: `none`
`project_id`	Integer (int64)	Example: `1`
`raw_url`	String	Example: `http://example.com/example/example/snippets/1/raw`
`ssh_url_to_repo`	String	Example: `ssh://user@gitlab.example.com/snippets/65.git`
`title`	String	Example: `test`
`updated_at`	String (date-time)	Example: `2012-06-28T10:52:04Z`
`visibility`	String	Example: `public`
`web_url`	String	Example: `http://example.com/example/example/snippets/1`

APIEntitiesProjectSnippet

Property	Type	Description
`author`	APIEntitiesUserBasic	—
`created_at`	String (date-time)	Example: `2012-06-28T10:52:04Z`
`description`	String	Example: `Ruby test snippet`
`file_name`	String	Example: `add.rb`
`files`	Array of objects	Example: `[{"path":"file.txt","raw_url":"https://gitlab.example.com/.../raw"}]`
`http_url_to_repo`	String	Example: `https://gitlab.example.com/snippets/65.git`
`id`	Integer (int64)	Example: `1`
`imported`	Boolean	Example: `false`
`imported_from`	String	Example: `none`
`project_id`	Integer (int64)	Example: `1`
`raw_url`	String	Example: `http://example.com/example/example/snippets/1/raw`
`ssh_url_to_repo`	String	Example: `ssh://user@gitlab.example.com/snippets/65.git`
`title`	String	Example: `test`
`updated_at`	String (date-time)	Example: `2012-06-28T10:52:04Z`
`visibility`	String	Example: `public`
`web_url`	String	Example: `http://example.com/example/example/snippets/1`

APIEntitiesSnippet

Property	Type	Description
`author`	APIEntitiesUserBasic	—
`created_at`	String (date-time)	Example: `2012-06-28T10:52:04Z`
`description`	String	Example: `Ruby test snippet`
`file_name`	String	Example: `add.rb`
`files`	Array of objects	Example: `[{"path":"file.txt","raw_url":"https://gitlab.example.com/.../raw"}]`
`http_url_to_repo`	String	Example: `https://gitlab.example.com/snippets/65.git`
`id`	Integer (int64)	Example: `1`
`imported`	Boolean	Example: `false`
`imported_from`	String	Example: `none`
`project_id`	Integer (int64)	Example: `1`
`raw_url`	String	Example: `http://example.com/example/example/snippets/1/raw`
`ssh_url_to_repo`	String	Example: `ssh://user@gitlab.example.com/snippets/65.git`
`title`	String	Example: `test`
`updated_at`	String (date-time)	Example: `2012-06-28T10:52:04Z`
`visibility`	String	Example: `public`
`web_url`	String	Example: `http://example.com/example/example/snippets/1`

APIEntitiesUserAgentDetail

Property	Type	Description
`akismet_submitted`	Boolean	Example: `false`
`ip_address`	String	Example: `127.0.0.1`
`user_agent`	String	Example: `AppleWebKit/537.36`

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

List all snippets for a project

Create a project snippet

Retrieve a project snippet

Update a project snippet

Delete a project snippet

Retrieve snippet repository file content

Retrieve a raw project snippet

Retrieve user agent details for a project snippet

List all snippets for current user

Create a snippet

List all snippets

List all public snippets

Retrieve a snippet

Update snippet

Delete snippet

Retrieve snippet file content

Retrieve a raw snippet

Retrieve user agent details for a snippet

Schemas

APIEntitiesCustomAttribute

APIEntitiesPersonalSnippet

APIEntitiesProjectSnippet

APIEntitiesSnippet

APIEntitiesUserAgentDetail

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error