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	The ID or URL-encoded path of the project
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	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	The 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`
`description`	String	The description of a snippet
`file_name` Required	String	The name of a snippet file
`files`	Array of objects	An array of files. Mutually exclusive with `content`
`files[].content` Required	String	The content of a snippet file
`files[].file_path` Required	String	The path of a snippet file
`title` Required	String	The title of the snippet
`visibility` Required	String	The visibility of the snippet 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	The ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	The ID of a project 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	The ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	The ID of a project snippet

Request body (application/json)

Property	Type	Description
`content`	String	The content of the snippet. Mutually exclusive with `files`
`description`	String	The description of a snippet
`file_name`	String	The file name of the snippet. Mutually exclusive with `files`
`files`	Array of objects	An array of files to update. Mutually exclusive with `content`, `file_name`
`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	The content of a snippet
`files[].file_path`	String	The file path of a snippet file
`files[].previous_path`	String	The previous path of a snippet file
`title`	String	The title of the snippet
`visibility`	String	The visibility of the snippet 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	The ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	The ID of a project 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	The 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	The ID of a project 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	The ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	The ID of a project 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	The ID or URL-encoded path of the project
`snippet_id` Path, required	Integer	The ID of a project 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 after the specified time
`created_before` Query	String (date-time)	Return snippets created before the specified time
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	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`
`description`	String	The description of a snippet
`file_name` Required	String	The name of a snippet file
`files`	Array of objects	An array of files. Mutually exclusive with `content`
`files[].content` Required	String	The content of a snippet file
`files[].file_path` Required	String	The path of a snippet file
`title` Required	String	The title of a snippet
`visibility`	String	The visibility of the snippet 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 after the specified time
`created_before` Query	String (date-time)	Return snippets created before the specified time
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	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 after the specified time
`created_before` Query	String (date-time)	Return snippets created before the specified time
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	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	The ID of a 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	The ID of a snippet

Request body (application/json)

Property	Type	Description
`content`	String	The content of a snippet. Mutually exclusive with `files`
`description`	String	The description of a snippet
`file_name`	String	The name of a snippet file. Mutually exclusive with `files`
`files`	Array of objects	An array of files to update. Mutually exclusive with `content`, `file_name`
`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	The content of a snippet
`files[].file_path`	String	The file path of a snippet file
`files[].previous_path`	String	The previous path of a snippet file
`title`	String	The title of a snippet
`visibility`	String	The visibility of the snippet 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	The ID of a 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	The ID of a 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	The ID of a 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	The ID of a 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