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:

Projects

Bitbucket Cloud projects make it easier for teams to focus on a goal, product, or process by organizing their repositories.

Create a project in a workspace

POST /2.0/workspaces/{workspace}/projects

Creates a new project.

Note that the avatar has to be embedded as either a data-url or a URL to an external image as shown in the examples below:

1
2
$ body=$(cat << EOF
{
    "name": "Mars Project",
    "key": "MARS",
    "description": "Software for colonizing mars.",
    "links": {
        "avatar": {
            "href": "data:image/gif;base64,R0lGODlhEAAQAMQAAORHHOVSKudfOulrSOp3WOyDZu6QdvCchPGolfO0o/..."
        }
    },
    "is_private": false
}
EOF
)
$ curl -H "Content-Type: application/json" \
       -X POST \
       -d "$body" \
       https://api.bitbucket.org/2.0/teams/teams-in-space/projects/ | jq .
{
  // Serialized project document
}

or even:

1
2
$ body=$(cat << EOF
{
    "name": "Mars Project",
    "key": "MARS",
    "description": "Software for colonizing mars.",
    "links": {
        "avatar": {
            "href": "http://i.imgur.com/72tRx4w.gif"
        }
    },
    "is_private": false
}
EOF
)
$ curl -H "Content-Type: application/json" \
       -X POST \
       -d "$body" \
       https://api.bitbucket.org/2.0/teams/teams-in-space/projects/ | jq .
{
  // Serialized project document
}
project:admin

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}.

Body parameters
Content typeValue
application/json

allOf [object, Project]

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
curl --request POST \
  --url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/projects' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "links": {
    "html": {
      "href": "<string>",
      "name": "<string>"
    },
    "avatar": {
      "href": "<string>",
      "name": "<string>"
    }
  },
  "uuid": "<string>",
  "key": "<string>",
  "owner": {
    "type": "<string>"
  },
  "name": "<string>",
  "description": "<string>",
  "is_private": true,
  "created_on": "<string>",
  "updated_on": "<string>",
  "has_publicly_visible_repos": true
}'

Responses

A new project has been created.

Content typeValue
application/json

allOf [object, Project]

Header Parameters
Location

string

The location of the newly created project

Get a project for a workspace

GET /2.0/workspaces/{workspace}/projects/{project_key}

Returns the requested project.

project

Request

Path parameters
project_key Required

string

The project in question. This is the actual key assigned to the project.

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/workspaces/{workspace}/projects/{project_key}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

The project that is part of a workspace.

Content typeValue
application/json

allOf [object, Project]

Update a project for a workspace

PUT /2.0/workspaces/{workspace}/projects/{project_key}

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

Creation

See the POST documentation for the project collection for an example of the request body.

Note: The key should not be specified in the body of request (since it is already present in the URL). The name is required, everything else is optional.

Update

See the POST documentation for the project collection for an example of the request body.

Note: The key is not required in the body (since it is already in the URL). The key may be specified in the body, if the intent is to change the key itself. In such a scenario, the location of the project is changed and is returned in the Location header of the response.

project:admin

Request

Path parameters
project_key Required

string

The project in question. This is the actual key assigned to the project.

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, Project]

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
curl --request PUT \
  --url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/projects/{project_key}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "links": {
    "html": {
      "href": "<string>",
      "name": "<string>"
    },
    "avatar": {
      "href": "<string>",
      "name": "<string>"
    }
  },
  "uuid": "<string>",
  "key": "<string>",
  "owner": {
    "type": "<string>"
  },
  "name": "<string>",
  "description": "<string>",
  "is_private": true,
  "created_on": "<string>",
  "updated_on": "<string>",
  "has_publicly_visible_repos": true
}'

Responses

The existing project is has been updated.

Content typeValue
application/json

allOf [object, Project]

Header Parameters
Location

string

The location of the project. This header is only provided when the project key is updated.

Delete a project for a workspace

DELETE /2.0/workspaces/{workspace}/projects/{project_key}

Deletes this project. This is an irreversible operation.

You cannot delete a project that still contains repositories. To delete the project, delete or transfer the repositories first.

Example:

1
2
$ curl -X DELETE https://api.bitbucket.org/2.0/bbworkspace1/PROJ
project:admin

Request

Path parameters
project_key Required

string

The project in question. This is the actual key assigned to the project.

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
curl --request DELETE \
  --url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/projects/{project_key}' \
  --header 'Authorization: Bearer <access_token>'

Responses

Successful deletion.

List the default reviewers in a project

GET /2.0/workspaces/{workspace}/projects/{project_key}/default-reviewers

Return a list of all default reviewers for a project. This is a list of users that will be added as default reviewers to pull requests for any repository within the project.

Example:

1
2
$ curl https://api.bitbucket.org/2.0/.../projects/.../default-reviewers | jq .
{
    "pagelen": 10,
    "values": [
        {
            "user": {
                "display_name": "Davis Lee",
                "uuid": "{f0e0e8e9-66c1-4b85-a784-44a9eb9ef1a6}"
            },
            "reviewer_type": "project",
            "type": "default_reviewer"
        },
        {
            "user": {
                "display_name": "Jorge Rodriguez",
                "uuid": "{1aa43376-260d-4a0b-9660-f62672b9655d}"
            },
            "reviewer_type": "project",
            "type": "default_reviewer"
        }
    ],
    "page": 1,
    "size": 2
}
project:admin

Request

Path parameters
project_key Required

string

The project in question. This is the actual key assigned to the project.

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/workspaces/{workspace}/projects/{project_key}/default-reviewers' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses