Addon
Branch restrictions
Branching model
Commit statuses
Commits
Deployments
Downloads
Issue tracker
Pipelines
Projects
Pullrequests
Refs
Reports
Repositories
Snippets
Source
Ssh
Teams
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.

List a projects for a team

Deprecated

GET /2.0/teams/{username}/projects/

This endpoint has been removed. You should use the workspace projects endpoint instead. For more information, see the announcement.

OAuth scopes required
project

Request

Path parameters
username Required

string

This can either be the username or the UUID of the account, surrounded by curly-braces, for example: {account UUID}. An account is either a team or user.

Example

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

Responses

A paginated list of projects that belong to the specified team.

Content typeValue
application/json

Paginated Projects

Create a project for a team

Deprecated

POST /2.0/teams/{username}/projects/

Creates a new project.

This endpoint has been removed. You should use the workspace projects endpoint instead. For more information, see the announcement.

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
}
OAuth scopes required
project:write

Request

Path parameters
username Required

string

This can either be the username or the UUID of the account, surrounded by curly-braces, for example: {account UUID}. An account is either a team or user.

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/teams/{username}/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

Deprecated

GET /2.0/teams/{username}/projects/{project_key}

This endpoint has been removed. You should use the workspace project endpoint instead. For more information, see the announcement.

OAuth scopes required
project

Request

Path parameters
project_key Required

string

The project in question. This can either be the actual key assigned to the project or the UUID (surrounded by curly-braces ({})).

username Required

string

This can either be the username or the UUID of the account, surrounded by curly-braces, for example: {account UUID}. An account is either a team or user.

Example

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

Responses

The project object.

Content typeValue
application/json

allOf [object, Project]

Update a project

Deprecated

PUT /2.0/teams/{username}/projects/{project_key}

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

This endpoint has been removed. You should use the workspace project endpoint instead. For more information, see the announcement.

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.

OAuth scopes required
project:write

Request

Path parameters
project_key Required

string

The project in question. This can either be the actual key assigned to the project or the UUID (surrounded by curly-braces ({})).

username Required

string

This can either be the username or the UUID of the account, surrounded by curly-braces, for example: {account UUID}. An account is either a team or user.

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/teams/{username}/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

Deprecated

DELETE /2.0/teams/{username}/projects/{project_key}

This endpoint has been removed. You should use the workspace project endpoint instead. For more information, see the announcement.

OAuth scopes required
project:write

Request

Path parameters
project_key Required

string

The project in question. This can either be the actual key assigned to the project or the UUID (surrounded by curly-braces ({})).

username Required

string

This can either be the username or the UUID of the account, surrounded by curly-braces, for example: {account UUID}. An account is either a team or user.

Example

1
2
3
curl --request DELETE \
  --url 'https://api.bitbucket.org/2.0/teams/{username}/projects/{project_key}' \
  --header 'Authorization: Bearer <access_token>'

Responses

Successful deletion.

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
}
OAuth scopes required
project:write

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.

OAuth scopes required
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