Bitbucket API's

[#1]

Hi Community,

In the series of APIs in Atlassian Universe, here we look at Bitbucket APIs that allow us to interact with our access to Bitbucket with Workspaces, Projects, and Repositories.

Token created in our Bitbucket Account will help us to access API endpoints and authenticate to Bitbucket Cloud

To create a Token, login into your account and navigate to the URL - https://bitbucket.org/account/settings

In the App Passwords section, create an App Password with the name and appropriate scope for you to either just read the contents in your workspace, or modify to perform some configurations.

Create the Token with appropriate Permissions

List of App Passwords

To Clone the Repository using the Token, the syntax would be

git clone https://username:token@bitbucket.org/workspace-name/repo-name.git

Replace the token with the actual token you have generated in the App Passwords section

You will get the username when you clone the repo by default and it can be found in the Profile Settings section

Most users in Bitbucket have the requirement to interact with the Groups endpoint and add the users to the repository and such scenarios are supported by the v1 version of Bitbucket Cloud API - v1 Bitbucket APIs

Bitbucket Groups API - Here

APIs query and manipulate the group privileges - Here

Endpoints Support in Bitbucket Groups  v1 REST APIs

• /1.0/groups
• /1.0/group-privileges
• /1.0/invitations
• /1.0/users/{accountname}/invitations

Below are the examples of Bitbucket APIs

Note: jq should be installed to extract the JSON response and the terminal should be bash or Linux environment or git terminal will also work

List all Repositories in a Workspace

curl -s -X GET --user "${username}:${token}" -H 'Content-Type: application/json' --url "https://api.bitbucket.org/2.0/repositories/${workspace}?pagelen=${pagelen}&page=${pageno}" | jq -r ".values[] | [.project.name, .slug, .updated_on, .size] | @csv" | awk -F "," 'BEGIN { OFS=", " } {print $1, $2, substr($3,1,11), $4}' |  tr -d '"'

Get User Permissions for a Repository

curl -s -X GET --user "${username}:${token}" -H 'Content-Type: application/json' --url "https://api.bitbucket.org/2.0/workspaces/${workspace}/permissions/repositories/${repo}" | jq -r '.values[] | [.repository.name, .user.display_name, .permission] | @csv' | tr -d '"' >> userpermissons.csv

Get Webhooks for a Repository

curl -s -X GET --user "${username}:${token}" -H 'Content-Type: application/json' --url "https://api.bitbucket.org/2.0/repositories/${workspace}/${repo}/hooks" | jq -r '.values[] | [.subject.name, .url] | @csv' | tr -d '"'

Here are some examples of how to use v1 APIs and get the information of groups, permissions in a repository, and other such information

Get Group Permissions for a Repository

curl -s --request GET --user "${username}:${token}" "https://api.bitbucket.org/1.0/group-privileges/${workspace}/${repo}" | jq -r '.[] | [.repository.slug, .group.slug, .privilege] | @csv' | tr -d '"' >> groupspermissons.csv

Update Group with Read Permission for a Repository

curl -s --request PUT --user "${username}:${token}" https://api.bitbucket.org/1.0/group-privileges/${workspace}/${reponame}/${workspace}/${groupname} --data "read"

Hope the Guide to the Bitbucket API will enrich your knowledge and help you with the required actions you want to achieve in your work

Do let us know if there are useful suggestions, better improvements, and helpful tips on how you manage the automation

Thanks,
Pramodh

[Ulrich Kuhnhardt _IzymesCo_]

Thanks for sharing these useful APIs. Do you still use v1 APIs? Atlassian announced deprecation (2018) and removal (2019) ?

[Michael Walker]

Hey Ulrich,

We do still use the v1.0 API for 4 distinct endpoints, as discussed here, as these specifically don't have a v2.0 equivalent. We didn't want to revoke your ability to get access to that data so we left the 1.0 in place for the time being.

The goal in the future is for Bitbucket to integrate with the Atlassian Admin hub and then this specific data can be managed there, rather than directly in Bitbucket, hence the reason that we never created a 2.0 equivalent. You can see more on our Bitbucket Cloud Roadmap.

[Ulrich Kuhnhardt _IzymesCo_]

Thank you @Michael Walker for the clarification. What is the best way to retrieve a list of repository groups via a named search query for a user with repo admin permissions (the user is not workspace/account owner)?

[Pramodh M]

Hi @Ulrich Kuhnhardt _IzymesCo_

You would still make the same call as I have explained in the Article

curl -s --request GET --user "${username}:${token}" "https://api.bitbucket.org/1.0/group-privileges/${workspace}/${repo}" | jq -r '.[] | [.repository.slug, .group.slug, .privilege] | @csv' | tr -d '"' >> groupspermissons.csv

and then filter the result with admin privileges as it would return all the data

Note: I'm using jq to filter JSON data and then converting it to CSV

Thanks,
Pramodh