The extended "contents" API, to get file metadata and/or content, or list a directory.
const url = 'https://gitea.com/api/v1/repos/example/example/contents-ext/example';const options = {method: 'GET', headers: {Authorization: 'Basic <credentials>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://gitea.com/api/v1/repos/example/example/contents-ext/example \ --header 'Authorization: Basic <credentials>'It guarantees that only one of the response fields is set if the request succeeds. Users can pass “includes=file_content” or “includes=lfs_metadata” to retrieve more fields. “includes=file_content” only works for single file, if you need to retrieve file contents in batch, use “file-contents” API after listing the directory.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Owner of the repo
Name of the repo
Path of the dir, file, symlink or submodule in the repo. Swagger requires path parameter to be “required”, you can leave it empty or pass a single dot (“.”) to get the root directory.
Query Parameters
Section titled “Query Parameters”The name of the commit/branch/tag, default to the repository’s default branch.
By default this API’s response only contains file’s metadata. Use comma-separated “includes” options to retrieve more fields. Option “file_content” will try to retrieve the file content, “lfs_metadata” will try to retrieve LFS metadata, “commit_metadata” will try to retrieve commit metadata, and “commit_message” will try to retrieve commit message.
Responses
Section titled “Responses”object
DirContents contains directory listing when the path represents a directory
ContentsResponse contains information about a repo’s entry’s (dir, file, symlink, submodule) metadata and content
object
FileLinksResponse contains the links for a repo’s file
object
GitURL is the Git API URL for this file
HTMLURL is the web URL for this file
Self is the API URL for this file
content is populated when type is file, otherwise null
DownloadURL is the direct download URL for this file
encoding is populated when type is file, otherwise null
GitURL is the Git API URL for this blob or tree
HTMLURL is the web URL for this file or directory
LastCommitMessage is the message of the last commit that affected this file
LastCommitSHA is the SHA of the last commit that affected this file
LfsOid is the Git LFS object ID if this file is stored in LFS
LfsSize is the file size if this file is stored in LFS
mode is the Git file mode as an octal string, e.g. 100644 (regular), 100755 (executable), 120000 (symlink), 160000 (submodule)
Name is the file or directory name
Path is the full path to the file or directory
SHA is the Git blob or tree SHA
Size is the file size in bytes
submodule_git_url is populated when type is submodule, otherwise null
target is populated when type is symlink, otherwise null
type will be file, dir, symlink, or submodule
URL is the API URL for this file or directory
ContentsResponse contains information about a repo’s entry’s (dir, file, symlink, submodule) metadata and content
object
FileLinksResponse contains the links for a repo’s file
object
GitURL is the Git API URL for this file
HTMLURL is the web URL for this file
Self is the API URL for this file
content is populated when type is file, otherwise null
DownloadURL is the direct download URL for this file
encoding is populated when type is file, otherwise null
GitURL is the Git API URL for this blob or tree
HTMLURL is the web URL for this file or directory
LastCommitMessage is the message of the last commit that affected this file
LastCommitSHA is the SHA of the last commit that affected this file
LfsOid is the Git LFS object ID if this file is stored in LFS
LfsSize is the file size if this file is stored in LFS
mode is the Git file mode as an octal string, e.g. 100644 (regular), 100755 (executable), 120000 (symlink), 160000 (submodule)
Name is the file or directory name
Path is the full path to the file or directory
SHA is the Git blob or tree SHA
Size is the file size in bytes
submodule_git_url is populated when type is submodule, otherwise null
target is populated when type is symlink, otherwise null
type will be file, dir, symlink, or submodule
URL is the API URL for this file or directory
Examplegenerated
{ "dir_contents": [ { "_links": { "git": "example", "html": "example", "self": "example" }, "content": "example", "download_url": "https://example.com", "encoding": "example", "git_url": "https://example.com", "html_url": "https://example.com", "last_author_date": "2026-04-15T12:00:00Z", "last_commit_message": "example", "last_commit_sha": "example", "last_committer_date": "2026-04-15T12:00:00Z", "lfs_oid": "example", "lfs_size": 1, "mode": "example", "name": "example", "path": "example", "sha": "example", "size": 1, "submodule_git_url": "https://example.com", "target": "example", "type": "example", "url": "https://example.com" } ], "file_contents": { "_links": { "git": "example", "html": "example", "self": "example" }, "content": "example", "download_url": "https://example.com", "encoding": "example", "git_url": "https://example.com", "html_url": "https://example.com", "last_author_date": "2026-04-15T12:00:00Z", "last_commit_message": "example", "last_commit_sha": "example", "last_committer_date": "2026-04-15T12:00:00Z", "lfs_oid": "example", "lfs_size": 1, "mode": "example", "name": "example", "path": "example", "sha": "example", "size": 1, "submodule_git_url": "https://example.com", "target": "example", "type": "example", "url": "https://example.com" }}APINotFound is a not found empty response