Undocumented API V2 endpoint

Bitbucket Development Bitbucket Cloud
1

Hi

I’m using Bitbucket’s API to get hold of all the repositories that the authenticated user has at least read access to. This should include repos they own, repos their team owns and repos they’ve been directly added to.

The endpoint https://api.bitbucket.org/2.0/repositories/ returns all the public repos available.
Docs: https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories

The endpoint https://api.bitbucket.org/2.0/repositories/{username} returns all the repos owned by the given username (so it doesn’t include their team’s repos). This endpoint can be filtered using these role params in the query string:

  • admin
  • contributor
  • member
  • owner

Docs: https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/{username}

I’ve found that combining the all repos endpoint with the filtering of the query params offers exactly what I’m after:

https://api.bitbucket.org/2.0/repositories/?role=member

However, as far as I can tell this is not actually documented anywhere.

Is this a stable endpoint to use? Is it just the docs that are missing some information?

If it’s an unstable endpoint (or just a quirk that it works in the first place), can you advise me on an alternative?

Thanks
Ali

1 Like
2

Hi Ali,

It is stable to use the role parameter with the /repositories endpoint. As you may be able to deduce from the values of the role parameter, the system was designed to with the /repositories endpoint in mind. Passing in role=owner doesn’t have a lot of meaning if the username is included in the url. So it’s unfortunate our documentation didn’t reflect that. I will file an internal ticket to get the documentation updated.

One small correction to your sleuthing. By default the /repositories will return everything the user has access to. It does include public repositories, which may overwhelm the response, but will also include private repositories the user has access to. That can be useful in combination with filtering to remove those public repositories and return all private repositories a user has access, regardless of role.

Thanks, for bringing this to our attention,
Chris

3 Likes
3

Hi Chris

Thanks for speedy (and helpful) reply :slight_smile:

Ali