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

NameTypeDescription
id
Path, required		StringThe project ID
Example: gitlab-org/gitlab
file_path
Path, required		StringThe URL-encoded path to the file
Example: lib%2Fclass%2Erb
ref
Query, required		StringThe name of branch, tag or commit
Example: main

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
404Not 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

NameTypeDescription
id
Path, required		StringThe project ID
Example: gitlab-org/gitlab
file_path
Path, required		StringThe URL-encoded path to the file
Example: lib%2Fclass%2Erb

Request body (multipart/form-data)

PropertyTypeDescription
file
Required		String (binary)The file content to be created (generated by Multipart middleware)

Responses

CodeDescriptionSchema
201Created—
400Bad Request—
404Not 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

NameTypeDescription
id
Path, required		StringThe project ID
Example: gitlab-org/gitlab
file_path
Path, required		StringThe URL-encoded path to the file
Example: lib%2Fclass%2Erb

Request body (multipart/form-data)

PropertyTypeDescription
file
Required		String (binary)The file content to be updated (generated by Multipart middleware)

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
404Not 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

NameTypeDescription
id
Path, required		StringThe project ID
Example: gitlab-org/gitlab
file_path
Path, required		StringThe URL-encoded path to the file
Example: lib%2Fclass%2Erb
branch
Query, required		StringName of the branch to commit into. To create a new branch, also provide start_branch
Example: main
commit_message
Query, required		StringCommit message
Example: Initial commit
start_branch
Query		StringName of the branch to start the new commit from
Example: main
author_email
Query		StringThe email of the author
Example: johndoe@example.com
author_name
Query		StringThe name of the author
Example: John Doe
last_commit_id
Query		StringLast known file commit id
Example: 2695effb5807a22ff3d138d593fd856244e155e7

Responses

CodeDescriptionSchema
204No Content—
400Bad Request—
404Not Found—

Retrieve file metadata

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

Retrieves metadata for a specified file in a repository.

Parameters

NameTypeDescription
id
Path, required		StringThe project ID
Example: gitlab-org/gitlab
file_path
Path, required		StringThe URL-encoded path to the file
Example: lib%2Fclass%2Erb

Request body (application/json)

PropertyTypeDescription
ref
Required		StringThe name of branch, tag or commit
Example: main

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
404Not 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

NameTypeDescription
id
Path, required		StringThe project ID
Example: gitlab-org/gitlab
file_path
Path, required		StringThe URL-encoded path to the file
Example: lib%2Fclass%2Erb
ref
Query, required		StringThe name of branch, tag or commit
Example: main
range
Query		ObjectObject that contains the blame range
range[start]
Query, required		IntegerThe first line of the range to blame
Minimum: 1
range[end]
Query, required		IntegerThe last line of the range to blame
Minimum: 1

Responses

CodeDescriptionSchema
200OKAPIEntitiesBlameRange
400Bad Request—
404Not 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

NameTypeDescription
id
Path, required		StringThe project ID
Example: gitlab-org/gitlab
file_path
Path, required		StringThe URL-encoded path to the file
Example: lib%2Fclass%2Erb

Request body (application/json)

PropertyTypeDescription
ref
Required		StringThe name of branch, tag or commit
Example: main

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
404Not 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

NameTypeDescription
id
Path, required		StringThe project ID
Example: gitlab-org/gitlab
file_path
Path, required		StringThe URL-encoded path to the file
Example: lib%2Fclass%2Erb
ref
Query		StringThe name of branch, tag or commit
Example: main
lfs
Query		BooleanRetrieve binary data for a file that is an lfs pointer
Default: false

Responses

CodeDescriptionSchema
200OKString (binary) (application/octet-stream)
400Bad Request—
404Not Found—

Schemas

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

APIEntitiesBlameRange

PropertyTypeDescription
commitAPIEntitiesBlameRangeCommit—
linesArray of stringsExample: ["lorem ipsum"]

APIEntitiesBlameRangeCommit

PropertyTypeDescription
author_emailStringExample: john@example.com
author_nameStringExample: John Smith
authored_dateString (date-time)Example: 2012-05-28T04:42:42-07:00
committed_dateString (date-time)Example: 2012-05-28T04:42:42-07:00
committer_emailStringExample: jack@example.com
committer_nameStringExample: Jack Smith
idStringExample: 2695effb5807a22ff3d138d593fd856244e155e7
messageStringExample: Initial commit
parent_idsArray of stringsExample: ["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]
←
REST API / Features
REST API / Freeze periods
→