What is the api to be used to get list of all the files in a folder in a repository from bitbucket

malathi.pulakam February 27, 2023

I need list of all the files in a folder of a repository . what is the api to be used and what are all required to call that api properly (like to authenticate myself )

2 answers

0 votes
Theodora Boudale
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
February 28, 2023

Hi @malathi.pulakam and welcome to the community!

You can use the following endpoint to find files in a folder, at a certain branch or commit of the repository:

As Aron mentioned, in Git, the files of a repository can be different for different branches and commits. It is therefore necessary to provide in the API call the commit hash or branch name that you want to retrieve the files of.

An example call is the following:

curl -u BB_Username:App_password -X GET -H "Content-Type: application/json" https://api.bitbucket.org/2.0/repositories/{workspace-id}/{repo-slug}/src/{branch_or_commit-hash}/{path}


BB_Username is the username of a Bitbucket account with access to the repo
App_password is an app password for that account, with at least Repositories: Read permissions
{workspace-id} replace with the id of your workspace
{repo-slug} replace with the slug of your repo
{branch_or_commit-hash} replace with a commit hash or a branch name
{path} replace with the path of the folder in the repo that you want to see the files of

If you want to get fewer fields in the results, you can use the fields parameter:

curl -u BB_Username:App_password -X GET -H "Content-Type: application/json" https://api.bitbucket.org/2.0/repositories/{workspace-id}/{repo-slug}/src/{branch_or_commit-hash}/{path}/?fields=values.path,values.type

This will show only the path for each result, and whether it's a file or another directory.

With regards to authentication, in these examples, I used basic authentication which is tied to a certain user. You could also use Access tokens instead that are not tied to a certain user. You can find more details about access tokens here:

If you have any questions, please feel free to reach out!

Kind regards,

Fabio Fioramonti
I'm New Here
I'm New Here
Those new to the Atlassian Community have posted less than three times. Give them a warm welcome!
February 22, 2024

Hi @Theodora Boudale ,

there is a way to obtain the file SHA when listing content of a directory?

Something similar to what you might get with the command:

git ls-tree main

Thank you


Theodora Boudale
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
February 27, 2024

Hi Fabio,

I'm afraid that the file SHA is not returned by our API.

We have a feature request about this in our issue tracker:

The request was closed due to inactivity, but you can provide your feedback there, as our product managers continue to monitor even closed requests.

Kind regards,

0 votes
Aron Gombas _Midori_
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
February 28, 2023

I don't think there is such an API.

The folder/file hierarchy depends on a "snapshot of the repository", basically on a state identified by a hash (commit ID). Which means your client code should clone the repository using a given hash, then work with the cloned local repo with local filesystem operations I think.

Suggest an answer

Log in or Sign up to answer
AUG Leaders

Atlassian Community Events