Files

Use this API to manage repository files. You can also configure rate limits for this API.

Retrieve a file from a repository

GET /api/v4/projects/{id}/repository/files/{file_path}

Retrieves information about a specified file in a repository. This includes information like the name, size, and the file contents. File content is Base64 encoded.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project Example: `gitlab-org/gitlab`
`file_path` Path, required	String	URL-encoded full path to the file, for example `lib%2Fclass%2Erb` Example: `lib%2Fclass%2Erb`
`ref` Query, required	String	Commit SHA or name of a repository branch or tag Example: `main`

Responses

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

Create a file in a repository

POST /api/v4/projects/{id}/repository/files/{file_path}

Creates a file in a specified repository. Use the Commits API to create multiple files with a single request.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project Example: `gitlab-org/gitlab`
`file_path` Path, required	String	URL-encoded full path to the file, for example `lib%2Fclass%2Erb` Example: `lib%2Fclass%2Erb`

Request body (multipart/form-data)

Property	Type	Description
`file` Required	String (binary)	The file content to be created (generated by Multipart middleware)

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad Request	—
`404`	Not Found	—

Update a file in a repository

PUT /api/v4/projects/{id}/repository/files/{file_path}

Updates a specified file in a repository. Use the Commits API to update multiple files with a single request.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project Example: `gitlab-org/gitlab`
`file_path` Path, required	String	URL-encoded full path to the file, for example `lib%2Fclass%2Erb` Example: `lib%2Fclass%2Erb`

Request body (multipart/form-data)

Property	Type	Description
`file` Required	String (binary)	The file content to be updated (generated by Multipart middleware)

Responses

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

Delete a file in a repository

DELETE /api/v4/projects/{id}/repository/files/{file_path}

Deletes a specified file in a repository. Use the Commits API to delete multiple files with a single request.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project Example: `gitlab-org/gitlab`
`file_path` Path, required	String	URL-encoded full path to the file, for example `lib%2Fclass%2Erb` Example: `lib%2Fclass%2Erb`
`branch` Query, required	String	Name of the branch to commit the deletion into. Combine with `start_branch` to create a new branch Example: `main`
`commit_message` Query, required	String	Commit message Example: `Initial commit`
`start_branch` Query	String	Name of the base branch to create the branch from Example: `main`
`author_email` Query	String	Email address of the commit author Example: `johndoe@example.com`
`author_name` Query	String	Name of the commit author Example: `John Doe`
`last_commit_id` Query	String	Last known file commit ID Example: `2695effb5807a22ff3d138d593fd856244e155e7`

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

Retrieve file metadata

HEAD /api/v4/projects/{id}/repository/files/{file_path}

Retrieves metadata for a specified file in a repository.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project Example: `gitlab-org/gitlab`
`file_path` Path, required	String	URL-encoded full path to the file, for example `lib%2Fclass%2Erb` Example: `lib%2Fclass%2Erb`

Request body (application/json)

Property	Type	Description
`ref` Required	String	Commit SHA or name of a repository branch or tag Example: `main`

Responses

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

Retrieve file blame history from a repository

GET /api/v4/projects/{id}/repository/files/{file_path}/blame

Retrieves blame history for a specified file in a repository. Each blame range contains lines and their corresponding commit information.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project Example: `gitlab-org/gitlab`
`file_path` Path, required	String	URL-encoded full path to the file, for example `lib%2Fclass%2Erb` Example: `lib%2Fclass%2Erb`
`ref` Query, required	String	Commit SHA or name of a repository branch or tag Example: `main`
`range` Query	Object	Range of lines to return blame information for
`range[start]` Query, required	Integer	First line number of the range to blame Minimum: `1`
`range[end]` Query, required	Integer	Last line number of the range to blame Minimum: `1`

Responses

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

Retrieve file blame metadata

HEAD /api/v4/projects/{id}/repository/files/{file_path}/blame

Retrieves blame metadata for lines in a specified file.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project Example: `gitlab-org/gitlab`
`file_path` Path, required	String	URL-encoded full path to the file, for example `lib%2Fclass%2Erb` Example: `lib%2Fclass%2Erb`

Request body (application/json)

Property	Type	Description
`ref` Required	String	Commit SHA or name of a repository branch or tag Example: `main`

Responses

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

Retrieve a raw file from a repository

GET /api/v4/projects/{id}/repository/files/{file_path}/raw

Retrieves the raw file contents for a specified file in a repository.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project Example: `gitlab-org/gitlab`
`file_path` Path, required	String	URL-encoded full path to the file, for example `lib%2Fclass%2Erb` Example: `lib%2Fclass%2Erb`
`ref` Query	String	Commit SHA or name of a repository branch or tag Example: `main`
`lfs` Query	Boolean	If `true`, returns the Git LFS file contents instead of the pointer. Ignored if the file isn’t tracked by Git LFS Default: `false`

Responses

Code	Description	Schema
`200`	OK	String (binary) (`application/octet-stream`)
`400`	Bad Request	—
`404`	Not Found	—

Schemas

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

APIEntitiesBlameRange

Property	Type	Description
`commit`	APIEntitiesBlameRangeCommit	—
`lines`	Array of strings	Example: `["lorem ipsum"]`

APIEntitiesBlameRangeCommit

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`

Retrieve a file from a repository

Create a file in a repository

Update a file in a repository

Delete a file in a repository

Retrieve file metadata

Retrieve file blame history from a repository

Retrieve file blame metadata

Retrieve a raw file from a repository

Schemas

APIEntitiesBlameRange

APIEntitiesBlameRangeCommit

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