The Bitbucket Cloud REST API

Developer Day is June 9th, 2022. Register now for free!

Deployments

Teams are deploying code faster than ever, thanks to continuous delivery practices and tools like Bitbucket Pipelines. Bitbucket Deployments gives teams visibility into their deployment environments and helps teams to track how far changes have progressed in their deployment pipeline.

List deploy keys

GET /2.0/repositories/{workspace}/{repo_slug}/deploy-keys

Returns all deploy-keys belonging to a repository.

Example:

1
2
$ curl -H "Authorization <auth header>" \
https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-keys

Output:
{
    "pagelen": 10,
    "values": [
        {
            "id": 123,
            "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAK/b1cHHDr/TEV1JGQl+WjCwStKG6Bhrv0rFpEsYlyTBm1fzN0VOJJYn4ZOPCPJwqse6fGbXntEs+BbXiptR+++HycVgl65TMR0b5ul5AgwrVdZdT7qjCOCgaSV74/9xlHDK8oqgGnfA7ZoBBU+qpVyaloSjBdJfLtPY/xqj4yHnXKYzrtn/uFc4Kp9Tb7PUg9Io3qohSTGJGVHnsVblq/rToJG7L5xIo0OxK0SJSQ5vuId93ZuFZrCNMXj8JDHZeSEtjJzpRCBEXHxpOPhAcbm4MzULgkFHhAVgp4JbkrT99/wpvZ7r9AdkTg7HGqL3rlaDrEcWfL7Lu6TnhBdq5",
            "label": "mykey",
            "type": "deploy_key",
            "created_on": "2018-08-15T23:50:59.993890+00:00",
            "repository": {
                "full_name": "mleu/test",
                "name": "test",
                "type": "repository",
                "uuid": "{85d08b4e-571d-44e9-a507-fa476535aa98}"
            },
            "links":{
                "self":{
                    "href": "https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-keys/123"
                }
            }
            "last_used": null,
            "comment": "mleu@C02W454JHTD8"
        }
    ],
    "page": 1,
    "size": 1
}

OAuth scopes required:

repository

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

Example

cURL

Node.js

Java

Python

PHP

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

Responses

200

403

404

Deploy keys matching the repository

Content type	Value
application/json	Paginated Deploy Keys

Add a deploy key

POST /2.0/repositories/{workspace}/{repo_slug}/deploy-keys

Create a new deploy key in a repository. Note: If authenticating a deploy key with an OAuth consumer, any changes to the OAuth consumer will subsequently invalidate the deploy key.

Example:

1
2
$ curl -XPOST \
-H "Authorization <auth header>" \
-H "Content-type: application/json" \
https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-keys -d \
'{
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAK/b1cHHDr/TEV1JGQl+WjCwStKG6Bhrv0rFpEsYlyTBm1fzN0VOJJYn4ZOPCPJwqse6fGbXntEs+BbXiptR+++HycVgl65TMR0b5ul5AgwrVdZdT7qjCOCgaSV74/9xlHDK8oqgGnfA7ZoBBU+qpVyaloSjBdJfLtPY/xqj4yHnXKYzrtn/uFc4Kp9Tb7PUg9Io3qohSTGJGVHnsVblq/rToJG7L5xIo0OxK0SJSQ5vuId93ZuFZrCNMXj8JDHZeSEtjJzpRCBEXHxpOPhAcbm4MzULgkFHhAVgp4JbkrT99/wpvZ7r9AdkTg7HGqL3rlaDrEcWfL7Lu6TnhBdq5 mleu@C02W454JHTD8",
    "label": "mydeploykey"
}'

Output:
{
    "id": 123,
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAK/b1cHHDr/TEV1JGQl+WjCwStKG6Bhrv0rFpEsYlyTBm1fzN0VOJJYn4ZOPCPJwqse6fGbXntEs+BbXiptR+++HycVgl65TMR0b5ul5AgwrVdZdT7qjCOCgaSV74/9xlHDK8oqgGnfA7ZoBBU+qpVyaloSjBdJfLtPY/xqj4yHnXKYzrtn/uFc4Kp9Tb7PUg9Io3qohSTGJGVHnsVblq/rToJG7L5xIo0OxK0SJSQ5vuId93ZuFZrCNMXj8JDHZeSEtjJzpRCBEXHxpOPhAcbm4MzULgkFHhAVgp4JbkrT99/wpvZ7r9AdkTg7HGqL3rlaDrEcWfL7Lu6TnhBdq5",
    "label": "mydeploykey",
    "type": "deploy_key",
    "created_on": "2018-08-15T23:50:59.993890+00:00",
    "repository": {
        "full_name": "mleu/test",
        "name": "test",
        "type": "repository",
        "uuid": "{85d08b4e-571d-44e9-a507-fa476535aa98}"
    },
    "links":{
        "self":{
            "href": "https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-keys/123"
        }
    }
    "last_used": null,
    "comment": "mleu@C02W454JHTD8"
}

OAuth scopes required:

repository

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

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/deploy-keys' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

400

403

404

The deploy key that was created

Content type	Value
application/json	allOf [object, Deploy Key]

Get a deploy key

GET /2.0/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}

Returns the deploy key belonging to a specific key.

Example:

1
2
$ curl -H "Authorization <auth header>" \
https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-key/1234

Output:
{
    "comment": "mleu@C02W454JHTD8",
    "last_used": null,
    "links": {
        "self": {
            "href": https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-key/1234"
        }
    },
    "repository": {
        "full_name": "mleu/test",
        "name": "test",
        "type": "repository",
        "uuid": "{85d08b4e-571d-44e9-a507-fa476535aa98}"
    },
    "label": "mykey",
    "created_on": "2018-08-15T23:50:59.993890+00:00",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAK/b1cHHDr/TEV1JGQl+WjCwStKG6Bhrv0rFpEsYlyTBm1fzN0VOJJYn4ZOPCPJwqse6fGbXntEs+BbXiptR+++HycVgl65TMR0b5ul5AgwrVdZdT7qjCOCgaSV74/9xlHDK8oqgGnfA7ZoBBU+qpVyaloSjBdJfLtPY/xqj4yHnXKYzrtn/uFc4Kp9Tb7PUg9Io3qohSTGJGVHnsVblq/rToJG7L5xIo0OxK0SJSQ5vuId93ZuFZrCNMXj8JDHZeSEtjJzpRCBEXHxpOPhAcbm4MzULgkFHhAVgp4JbkrT99/wpvZ7r9AdkTg7HGqL3rlaDrEcWfL7Lu6TnhBdq5",
    "id": 1234,
    "type": "deploy_key"
}

OAuth scopes required:

repository

repository:admin

Request

Path parameters

key_id Required

string

The key ID matching the deploy key.

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

cURL

Node.js

Java

Python

PHP

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

Responses

200

403

404

Deploy key matching the key ID

Content type	Value
application/json	allOf [object, Deploy Key]

Update a deploy key

PUT /2.0/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}

Create a new deploy key in a repository.

The same key needs to be passed in but the comment and label can change.

Example:

1
2
$ curl -XPUT \
-H "Authorization <auth header>" \
-H "Content-type: application/json" \
https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-keys/1234 -d \
'{
    "label": "newlabel",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAK/b1cHHDr/TEV1JGQl+WjCwStKG6Bhrv0rFpEsYlyTBm1fzN0VOJJYn4ZOPCPJwqse6fGbXntEs+BbXiptR+++HycVgl65TMR0b5ul5AgwrVdZdT7qjCOCgaSV74/9xlHDK8oqgGnfA7ZoBBU+qpVyaloSjBdJfLtPY/xqj4yHnXKYzrtn/uFc4Kp9Tb7PUg9Io3qohSTGJGVHnsVblq/rToJG7L5xIo0OxK0SJSQ5vuId93ZuFZrCNMXj8JDHZeSEtjJzpRCBEXHxpOPhAcbm4MzULgkFHhAVgp4JbkrT99/wpvZ7r9AdkTg7HGqL3rlaDrEcWfL7Lu6TnhBdq5 newcomment",
}'

Output:
{
    "comment": "newcomment",
    "last_used": null,
    "links": {
        "self": {
            "href": "https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-keys/1234"
        }
    },
    "repository": {
        "full_name": "mleu/test",
        "name": "test",
        "type": "repository",
        "uuid": "{85d08b4e-571d-44e9-a507-fa476535aa98}"
    },
    "label": "newlabel",
    "created_on": "2018-08-15T23:50:59.993890+00:00",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAK/b1cHHDr/TEV1JGQl+WjCwStKG6Bhrv0rFpEsYlyTBm1fzN0VOJJYn4ZOPCPJwqse6fGbXntEs+BbXiptR+++HycVgl65TMR0b5ul5AgwrVdZdT7qjCOCgaSV74/9xlHDK8oqgGnfA7ZoBBU+qpVyaloSjBdJfLtPY/xqj4yHnXKYzrtn/uFc4Kp9Tb7PUg9Io3qohSTGJGVHnsVblq/rToJG7L5xIo0OxK0SJSQ5vuId93ZuFZrCNMXj8JDHZeSEtjJzpRCBEXHxpOPhAcbm4MzULgkFHhAVgp4JbkrT99/wpvZ7r9AdkTg7HGqL3rlaDrEcWfL7Lu6TnhBdq5",
    "id": 1234,
    "type": "deploy_key"
}

OAuth scopes required:

repository

repository:admin

Request

Path parameters

key_id Required

string

The key ID matching the deploy key.

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

cURL

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

400

403

404

The newly updated deploy key.

Content type	Value
application/json	allOf [object, Deploy Key]

Delete a deploy key

DELETE /2.0/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}

This deletes a deploy key from a repository.

Example:

1
2
$ curl -XDELETE \
-H "Authorization <auth header>" \
https://api.bitbucket.org/2.0/repositories/mleu/test/deploy-keys/1234

OAuth scopes required:

repository

repository:admin

Request

Path parameters

key_id Required

string

The key ID matching the deploy key.

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

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/deploy-keys/{key_id}' \
  --header 'Authorization: Bearer <access_token>'

Responses

204

403

404

The key has been deleted

List deployments

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

Find deployments

OAuth scopes required:

NONE

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

repo_slug Required

string

The repository.

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/deployments/' \
  --header 'Accept: application/json'

Responses

200

The matching deployments.

Content type	Value
application/json	Paginated Deployments

Get a deployment

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

Retrieve a deployment

OAuth scopes required:

NONE

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

repo_slug Required

string

The repository.

deployment_uuid Required

string

The deployment UUID.

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/deployments/{deployment_uuid}' \
  --header 'Accept: application/json'

Responses

200

404

The deployment.

Content type	Value
application/json	allOf [object, Deployment]

List environments

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

Find environments

OAuth scopes required:

NONE