Addon
Branch restrictions
Branching model
Commit statuses
Commits
Deployments
Downloads
Issue tracker
Pipelines
Projects
Pullrequests
Refs
Reports
Repositories
Snippets
Source
Ssh
Users
Webhooks
Workspaces
Other operations

Rate this page:

Repositories

A Git repository is a virtual storage of your project. It allows you to save versions of your code, which you can access when needed. The repo resource allows you to access public repos, or repos that belong to a specific workspace.

List public repositories

GET /2.0/repositories

Returns a paginated list of all public repositories.

This endpoint also supports filtering and sorting of the results. See filtering and sorting for more details.

repository

Request

Query parameters
after

string

role

string

Filters the result based on the authenticated user's role on each repository.

  • member: returns repositories to which the user has explicit read access
  • contributor: returns repositories to which the user has explicit write access
  • admin: returns repositories to which the user has explicit administrator access
  • owner: returns all repositories owned by the current user

Valid values: admin, contributor, member, owner

q

string

Query string to narrow down the response as per filtering and sorting. role parameter must also be specified.

sort

string

Field by which the results should be sorted as per filtering and sorting.

Example

1
2
3
4
curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

All public repositories.

Content typeValue
application/json

Paginated Repositories

Retrieve the inheritance state for repository settings

GET /2.0/repositories/{workspace_slug}/{repo_slug}/override-settings

repository:admin

Request

Path parameters
repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace_slug Required

string

Example

1
2
3
4
curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace_slug}/{repo_slug}/override-settings' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

The repository setting inheritance state

Content typeValue
application/json

Repository Inheritance State

Set the inheritance state for repository settings

PUT /2.0/repositories/{workspace_slug}/{repo_slug}/override-settings

repository:admin

Request

Path parameters
repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace_slug Required

string

Example

1
2
3
curl --request PUT \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace_slug}/{repo_slug}/override-settings' \
  --header 'Authorization: Bearer <access_token>'

Responses

The repository setting inheritance state was set and no content returned

List repositories in a workspace

GET /2.0/repositories/{workspace}

Returns a paginated list of all repositories owned by the specified workspace.

The result can be narrowed down based on the authenticated user's role.

E.g. with ?role=contributor, only those repositories that the authenticated user has write access to are returned (this includes any repo the user is an admin on, as that implies write access).

This endpoint also supports filtering and sorting of the results. See filtering and sorting for more details.

repository

Request

Path parameters
workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Query parameters
role

string

Filters the result based on the authenticated user's role on each repository.

  • member: returns repositories to which the user has explicit read access
  • contributor: returns repositories to which the user has explicit write access
  • admin: returns repositories to which the user has explicit administrator access
  • owner: returns all repositories owned by the current user

Valid values: admin, contributor, member, owner

q

string

Query string to narrow down the response as per filtering and sorting.

sort

string

Field by which the results should be sorted as per filtering and sorting.

Example

1
2
3
4
curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

The repositories owned by the specified account.

Content typeValue
application/json

Paginated Repositories

Get a repository

GET /2.0/repositories/{workspace}/{repo_slug}

Returns the object describing this repository.

repository

Request

Path parameters
repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

1
2
3
4
curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

The repository object.

Content typeValue
application/json

allOf [object, Repository]

Update a repository

PUT /2.0/repositories/{workspace}/{repo_slug}

Since this endpoint can be used to both update and to create a repository, the request body depends on the intent.

Creation

See the POST documentation for the repository endpoint for an example of the request body.

Update

Note: Changing the name of the repository will cause the location to be changed. This is because the URL of the repo is derived from the name (a process called slugification). In such a scenario, it is possible for the request to fail if the newly created slug conflicts with an existing repository's slug. But if there is no conflict, the new location will be returned in the Location header of the response.

repository:admin

Request

Path parameters
repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Body parameters
Content typeValue
application/json

allOf [object, Repository]

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
curl --request PUT \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "links": {
    "self": {
      "href": "<string>",
      "name": "<string>"
    },
    "html": {
      "href": "<string>",
      "name": "<string>"
    },
    "avatar": {
      "href": "<string>",
      "name": "<string>"
    },
    "pullrequests": {
      "href": "<string>",
      "name": "<string>"
    },
    "commits": {
      "href": "<string>",
      "name": "<string>"
    },
    "forks": {
      "href": "<string>",
      "name": "<string>"
    },
    "watchers": {
      "href": "<string>",
      "name": "<string>"
    },
    "downloads": {
      "href": "<string>",
      "name": "<string>"
    },
    "clone": [
      {
        "href": "<string>",
        "name": "<string>"
      }
    ],
    "hooks": {
      "href": "<string>",
      "name": "<string>"
    }
  },
  "uuid": "<string>",
  "full_name": "<string>",
  "is_private": true,
  "parent": {
    "type": "<string>"
  },
  "scm": "git",
  "owner": {
    "type": "<string>"
  },
  "name": "<string>",
  "description": "<string>",
  "created_on": "<string>",
  "updated_on": "<string>",
  "size": 2154,
  "language": "<string>",
  "has_issues": true,
  "has_wiki": true,
  "fork_policy": "allow_forks",
  "project": {
    "type": "<string>"
  },
  "mainbranch": {
    "type": "<string>"
  }
}'

Responses

The existing repository has been updated

Content typeValue
application/json

allOf [object, Repository]

Header Parameters
Location

string

The location of the repository. This header is only provided when the repository's name is changed.

Create a repository

POST /2.0/repositories/{workspace}/{repo_slug}

Creates a new repository.

Note: In order to set the project for the newly created repository, pass in either the project key or the project UUID as part of the request body as shown in the examples below:

1
2
$ curl -X POST -H "Content-Type: application/json" -d '{
    "scm": "git",
    "project": {
        "key": "MARS"
    }
}' https://api.bitbucket.org/2.0/repositories/teamsinspace/hablanding

or

1
2
$ curl -X POST -H "Content-Type: application/json" -d '{
    "scm": "git",
    "project": {
        "key": "{ba516952-992a-4c2d-acbd-17d502922f96}"
    }
}' https://api.bitbucket.org/2.0/repositories/teamsinspace/hablanding

The project must be assigned for all repositories. If the project is not provided, the repository is automatically assigned to the oldest project in the workspace.

Note: In the examples above, the workspace ID teamsinspace, and/or the repository name hablanding can be replaced by UUIDs.