### Example Response for Get Configuration Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines This is an example of the JSON response you will receive when successfully retrieving the repository pipelines configuration. ```json { "type": "", "enabled": true, "repository": { "type": "" } } ``` -------------------------------- ### Post Install Redirect Configuration Example Source: https://developer.atlassian.com/cloud/bitbucket/modules/post-install-redirect This snippet shows how to configure the postInstallRedirect module in your app descriptor to redirect users to a specified URL after installation. The URL can include context parameters like user_username, user_uuid, and user_type. ```json { "modules": { "postInstallRedirect": { "key": "redirect", "url": "http://www.example.com?user={user_username}" } } } ``` -------------------------------- ### Install Button using Atlaskit Source: https://developer.atlassian.com/cloud/bitbucket/install-an-app-from-your-site This example demonstrates how to create a styled install button using Atlaskit's CSS. Ensure you include the necessary Atlaskit CSS files for the button to render correctly. The `href` attribute points to the authorization URL. ```html ``` -------------------------------- ### Example App Descriptor with Account Context Source: https://developer.atlassian.com/cloud/bitbucket/app-context This example demonstrates an app descriptor configuration that utilizes the 'account' context. This context limits the app's visibility to the account or team that installed it. ```json { "key": "example-app", "name": "Example App", "description": "An example app for Bitbucket", "vendor": { ... }, "baseUrl": { ... }, "lifecycle": { ... }, "modules": { ... }, "scopes": [...], "contexts": ["account"] } ``` -------------------------------- ### Basic Example Source: https://developer.atlassian.com/cloud/bitbucket/jsapi/events This example demonstrates how to subscribe to a custom event and emit it, triggering an alert. ```APIDOC ## Basic Example ```javascript //The following will create an alert message every time the event `customEvent` is triggered. AP.require('events', function(events){ events.on('customEvent', function(){ alert('event fired'); }); events.emit('customEvent'); }); ``` ``` -------------------------------- ### 200 OK Response for Get Deployment Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-deployments Example JSON response when a deployment is successfully retrieved. It includes the deployment's type, UUID, state, environment, and release information. ```json { "type": "", "uuid": "", "state": { "type": "" }, "environment": { "type": "" }, "release": { "type": "" } } ``` -------------------------------- ### List Repositories (Example) Source: https://developer.atlassian.com/cloud/bitbucket/oauth-2 This example demonstrates how to list all issues on a specific Bitbucket repository using the 2.0 API. ```APIDOC ## GET /repositories/{repo_owner}/{repo_name} ### Description Retrieves a list of repositories for a given owner. ### Method GET ### Endpoint `https://api.bitbucket.org/2.0/repositories/{repo_owner}/{repo_name}` ### Parameters #### Path Parameters - **repo_owner** (string) - Required - The username or team name of the repository owner. - **repo_name** (string) - Required - The name of the repository. ### Request Example ```bash curl https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.org ``` ### Response #### Success Response (200) Returns a JSON object containing repository information. ``` -------------------------------- ### Current User Response Example Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-users Example JSON response for the 'Get current user' API call, showing user details. ```json { "type": "", "links": { "avatar": {} }, "created_on": "", "display_name": "", "uuid": "" } ``` -------------------------------- ### Example 200 OK Response for Deploy Keys Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-deployments This is an example of a successful response when listing repository deploy keys. It includes pagination details and a list of deploy key objects, each with its ID, key, label, and associated repository information. ```json { "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 } ``` -------------------------------- ### Get Current History State Source: https://developer.atlassian.com/cloud/bitbucket/jsapi/history Use `getState()` to retrieve the current URL anchor. This example also shows how to push a new state before getting it. ```javascript AP.require(["history"], function(history){ history.pushState("page5"); history.getState(); // returns "page5"; }); ``` -------------------------------- ### Get Merge Task Status with Authentication Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests This example shows how to make a GET request to retrieve the merge task status, including the necessary authentication header. ```curl curl --request GET \ --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge/task-status/{task_id}' \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Get File History Request Example Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-source Example cURL request to fetch the history of a file, specifying workspace, repository slug, commit, and path. Includes authorization and accept headers. ```curl curl --request GET \ --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/filehistory/{commit}/{path}' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` -------------------------------- ### Example Project Deploy Key Response Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-deployments A sample JSON response for a successfully retrieved project deploy key. It includes details like the key's label, associated project, creation date, and the public key itself. ```json { "pagelen": 10, "values": [ { "comment": "thakseth@C02W454JHTD8", "last_used": null, "links": { "self": { "href": "https://api.bitbucket.org/2.0/workspaces/standard/projects/TEST_PROJECT/deploy-keys/1234" } } , "label": "test", "project": { "links": { "self": { "href": "https://api.bitbucket.org/2.0/workspaces/standard/projects/TEST_PROJECT" } }, "type": "project", "name": "cooperative standard", "key": "TEST_PROJECT", "uuid": "{3b3e510b-7f2b-414d-a2b7-76c4e405c1c0}" }, "created_on": "2021-07-28T21:20:19.491721+00:00", "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDX5yfMOEw6HG9jKTYTisbmDTJ4MCUTSVGr5e4OWvY3UuI2A6F8SdzQqa2f5BABA/4g5Sk5awJrYHlNu3EzV1V2I44tR3A4fnZAG71ZKyDPi1wvdO7UYmFgxV/Vd18H9QZFFjICGDM7W0PT2mI0kON/jN3qNWi+GiB/xgaeQKSqynysdysDp8lnnI/8Sh3ikURP9UP83ShRCpAXszOUNaa+UUlcYQYBDLIGowsg51c4PCkC3DNhAMxppkNRKoSOWwyl+oRVXHSDylkiJSBHW3HH4Q6WHieD54kGrjbhWBKdnnxKX7QAAZBDseY+t01N36m6/ljvXSUEcBWtHxBYye0r", "type": "project_deploy_key", "id": 1234 } ] } ``` -------------------------------- ### App Installation Link with addon_key Source: https://developer.atlassian.com/cloud/bitbucket/2019-11-18-installation-url Use this format for apps that have already been registered. Replace descriptor_uri with addon_key to ensure correct functionality. ```html https://bitbucket.org/site/addons/authorize?addon_key=&redirect_uri= ``` -------------------------------- ### Get Known Host Response Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines Example JSON response when successfully retrieving a known host. ```json { "type": "", "uuid": "", "hostname": "", "public_key": { "type": "" } } ``` -------------------------------- ### Example 200 OK Response for Deploy Key Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-deployments This is an example of a successful response when retrieving a deploy key. It includes details such as the key itself, its label, creation date, and associated repository information. ```json { "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" } ``` -------------------------------- ### Get default reviewer response Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-projects Example JSON response when a default reviewer is successfully retrieved. ```json { "display_name": "Davis Lee", "type": "user", "uuid": "{f0e0e8e9-66c1-4b85-a784-44a9eb9ef1a6}" } ``` -------------------------------- ### Get SSH Key Pair Response Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines Example JSON response when successfully retrieving an SSH key pair. ```json { "type": "", "private_key": "", "public_key": "" } ``` -------------------------------- ### Create Variable Response Example Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines Example of a successful response after creating a deployment variable, returning the details of the newly created variable. ```json { "type": "", "uuid": "", "key": "", "value": "", "secured": true } ``` -------------------------------- ### Get the client key of a Connect addon Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-addon Retrieves the client key for a specific Bitbucket Cloud Connect addon installation. ```APIDOC ## GET /addon/{addon_key}/client-key ### Description Retrieves the client key of a Connect addon. This key uniquely identifies a specific installation of an app. ### Method GET ### Endpoint https://api.bitbucket.org/2.0/addon/{addon_key}/client-key ### Parameters #### Path Parameters - **addon_key** (string) - Required - The unique key of the addon installation. ### Responses #### Success Response (200) - **client_key** (string) - The client key for the addon installation. #### Error Responses - **401** Unauthorized - **403** Forbidden - **404** Not Found ``` -------------------------------- ### List Variables Response Example Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines Example of a successful response when listing deployment variables, showing pagination details and a list of variables. ```json { "page": 102, "values": [ { "type": "", "uuid": "", "key": "", "value": "", "secured": true } ], "size": 142, "pagelen": 159, "next": "", "previous": "" } ``` -------------------------------- ### Retrieve Connect App Client Key using Forge API Source: https://developer.atlassian.com/cloud/bitbucket/connect-to-forge-migration-tooling Call the Bitbucket API from your Forge app to get the client key of a corresponding Connect app installation. This is useful for data migration and cleanup after the Forge equivalent is installed. ```javascript api.asApp().requestBitbucket(route`/2.0/addon/{addon-key}/client-key`) ``` -------------------------------- ### Example: Requesting all fields Source: https://developer.atlassian.com/cloud/bitbucket/rest Demonstrates how to use `fields=*` to discover and retrieve all available fields for a resource, including those not returned by default. ```APIDOC ## GET /{resource} ### Description Retrieves a resource and requests all available fields, including those that might be omitted by default, using `fields=*`. ### Method GET ### Endpoint /{resource} ### Parameters #### Query Parameters - **fields** (string) - Required - Use `*` to request all fields for the resource. ### Request Example ```bash curl https://api.bitbucket.org/2.0/users/evzijst?fields=* ``` ### Response #### Success Response (200) - **(all fields)** - All available fields for the user resource. #### Response Example ```json { "nickname": "evzijst", "account_status": "active", "website": "", "display_name": "Erik van Zijst", "uuid": "{a288a0ab-e13b-43f0-a689-c4ef0a249875}", "created_on": "2010-07-07T05:16:36+00:00", "location": null, "type": "user", "links": { "self": { "href": "https://api.bitbucket.org/2.0/users/evzijst" } } } ``` ``` -------------------------------- ### Get Tag Information Source: https://developer.atlassian.com/cloud/bitbucket/bitbucketcloud.postman.json Retrieves details for a specific tag in a repository. This example uses curl and jq to parse the JSON response. ```bash $ curl -s https://api.bitbucket.org/2.0/repositories/seanfarley/hg/refs/tags/3.8 -G | jq . { "name": "3.8", "links": { "commits": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/commits/3.8" }, "self": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/refs/tags/3.8" }, "html": { "href": "https://bitbucket.org/seanfarley/hg/commits/tag/3.8" } }, "tagger": { "raw": "Matt Mackall ", "type": "author", "user": { "username": "mpmselenic", "nickname": "mpmselenic", "display_name": "Matt Mackall", "type": "user", "uuid": "{a4934530-db4c-419c-a478-9ab4964c2ee7}", "links": { "self": { "href": "https://api.bitbucket.org/2.0/users/mpmselenic" }, "html": { "href": "https://bitbucket.org/mpmselenic/" }, "avatar": { "href": "https://bitbucket.org/account/mpmselenic/avatar/32/" } } } }, "date": "2016-05-01T18:52:25+00:00", "message": "Added tag 3.8 for changeset f85de28eae32", "type": "tag", "target": { "hash": "f85de28eae32e7d3064b1a1321309071bbaaa069", "repository": { "links": { "self": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg" }, "html": { "href": "https://bitbucket.org/seanfarley/hg" }, "avatar": { "href": "https://bitbucket.org/seanfarley/hg/avatar/32/" } }, "type": "repository", "name": "hg", "full_name": "seanfarley/hg", "uuid": "{c75687fb-e99d-4579-9087-190dbd406d30}" }, "links": { "self": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/commit/f85de28eae32e7d3064b1a1321309071bbaaa069" }, "comments": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/commit/f85de28eae32e7d3064b1a1321309071bbaaa069/comments" }, "patch": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/patch/f85de28eae32e7d3064b1a1321309071bbaaa069" }, "html": { "href": "https://bitbucket.org/seanfarley/hg/commits/f85de28eae32e7d3064b1a1321309071bbaaa069" }, "diff": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/diff/f85de28eae32e7d3064b1a1321309071bbaaa069" }, "approve": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/commit/f85de28eae32e7d3064b1a1321309071bbaaa069/approve" }, "statuses": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/commit/f85de28eae32e7d3064b1a1321309071bbaaa069/statuses" } }, "author": { "raw": "Sean Farley ", "type": "author", "user": { "username": "seanfarley", "nickname": "seanfarley", "display_name": "Sean Farley", "type": "user", "uuid": "{a295f8a8-5876-4d43-89b5-3ad8c6c3c51d}", "links": { "self": { "href": "https://api.bitbucket.org/2.0/users/seanfarley" }, "html": { "href": "https://bitbucket.org/seanfarley/" }, "avatar": { "href": "https://bitbucket.org/account/seanfarley/avatar/32/" } } } }, "parents": [ { "hash": "9a98d0e5b07fc60887f9d3d34d9ac7d536f470d2", "type": "commit", "links": { "self": { "href": "https://api.bitbucket.org/2.0/repositories/seanfarley/hg/commit/9a98d0e5b07fc60887f9d3d34d9ac7d536f470d2" }, "html": { "href": "https://bitbucket.org/seanfarley/hg/commits/9a98d0e5b07fc60887f9d3d34d9ac7d536f470d2" } } } ], "date": "2016-05-01T04:21:17+00:00", "message": "debian: alphabetize build deps", "type": "commit" } } ``` -------------------------------- ### CORS Request and Response Examples Source: https://developer.atlassian.com/cloud/bitbucket/rest/intro/#authentication Demonstrates how to perform a standard request and an OPTIONS request to verify CORS support. ```bash curl -i https://api.bitbucket.org -H "origin: http://bitbucket.com" ``` ```http HTTP/1.1 302 FOUND Server: nginx/1.6.2 Vary: Cookie Cache-Control: max-age=900 Content-Type: text/html; charset=utf-8 Strict-Transport-Security: max-age=31536000 Date: Tue, 21 Jun 2016 17:54:37 GMT Location: http://confluence.atlassian.com/x/IYBGDQ X-Served-By: app-110 X-Static-Version: 2c820eb0d2b3 ETag: "d41d8cd98f00b204e9800998ecf8427e" X-Content-Type-Options: nosniff X-Render-Time: 0.00379920005798 Connection: Keep-Alive X-Version: 2c820eb0d2b3 X-Frame-Options: SAMEORIGIN X-Request-Count: 383 X-Cache-Info: cached Content-Length: 0 ``` ```bash curl -i https://api.bitbucket.org -H "origin: http://bitbucket.com" -X OPTIONS ``` ```http HTTP/1.1 302 FOUND Server: nginx/1.6.2 Vary: Cookie Cache-Control: max-age=900 Content-Type: text/html; charset=utf-8 Access-Control-Expose-Headers: Accept-Ranges, Content-Encoding, Content-Length, Content-Type, ETag, Last-Modified Strict-Transport-Security: max-age=31536000 Date: Tue, 21 Jun 2016 18:04:30 GMT Access-Control-Max-Age: 86400 Location: http://confluence.atlassian.com/x/IYBGDQ X-Served-By: app-111 Access-Control-Allow-Origin: * X-Static-Version: 2c820eb0d2b3 ETag: "d41d8cd98f00b204e9800998ecf8427e" X-Content-Type-Options: nosniff X-Render-Time: 0.00371098518372 Connection: keep-alive X-Version: 2c820eb0d2b3 X-Frame-Options: SAMEORIGIN X-Request-Count: 357 Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS Access-Control-Allow-Headers: Accept, Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, Origin, Range, X-CsrftokenX-Requested-With X-Cache-Info: not cacheable; request wasn't a GET or HEAD Content-Length: 0 ``` -------------------------------- ### App Installation Link with descriptor_uri Source: https://developer.atlassian.com/cloud/bitbucket/2019-11-18-installation-url Use this format for apps that have not yet been registered. It includes the descriptor_uri and redirect_uri parameters. ```html https://bitbucket.org/site/addons/authorize?descriptor_uri=&redirect_uri= ``` -------------------------------- ### Get the client key of a Connect addon Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-addon Get the client key of the Connect addon associated with a Forge app install via forgeAppId linkage. This endpoint is part of the Connect -> Forge migration tooling and is intended to be used by a Forge app using `asApp().requestBitbucket()` only. ```APIDOC ## Get the client key of a Connect addon Get the client key of the Connect addon associated with a Forge app install via forgeAppId linkage. ### Method GET ### Endpoint /2.0/addon/{addon_key}/client-key ### Parameters #### Path Parameters - **addon_key** (string) - Required - The key of the addon. ### Responses #### Success Response (200) OK: The client key of the Connect addon linked to the Forge app installation where the request was made. #### Error Responses - 401 Unauthorized - 403 Forbidden - 404 Not Found ### Request Example ```bash curl --request GET \ --url 'https://api.bitbucket.org/2.0/addon/{addon_key}/client-key' \ --header 'Authorization: Bearer ' ``` ``` -------------------------------- ### Get User Information Source: https://developer.atlassian.com/cloud/bitbucket/oauth-2 Example of a request to retrieve a specific user's details. The response includes a 'links' element pointing to related resources. ```shell $ curl https://api.bitbucket.org/2.0/users/tutorials ``` -------------------------------- ### Create Project Deploy Key Request Example Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-deployments This cURL request demonstrates how to create a project deploy key. It requires an Authorization header and specifies the key and label in the JSON payload. ```shell curl --request POST \ --url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/projects/{project_key}/deploy-keys' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` -------------------------------- ### List Issues on a Repository (Example) Source: https://developer.atlassian.com/cloud/bitbucket/oauth-2 This example shows how to list all issues on a specific Bitbucket repository using the 1.0 API. ```APIDOC ## GET /repositories/{repo_owner}/{repo_name}/issues ### Description Retrieves a list of issues for a specific repository. ### Method GET ### Endpoint `https://api.bitbucket.org/1.0/repositories/{repo_owner}/{repo_name}/issues` ### Parameters #### Path Parameters - **repo_owner** (string) - Required - The username or team name of the repository owner. - **repo_name** (string) - Required - The name of the repository. ### Request Example ```bash curl https://api.bitbucket.org/1.0/repositories/tutorials/tutorials.bitbucket.org/issues ``` ### Response #### Success Response (200) Returns a JSON object containing a list of issues. ``` -------------------------------- ### Get a Specific Component Response Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-issue-tracker Example JSON response for a single issue tracker component. It includes the component's type, links, name, and ID. ```json { "type": "", "links": { "self": { "href": "", "name": "" } }, "name": "", "id": 2154 } ``` -------------------------------- ### Example Response for Get Group Permission Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-projects Illustrates the structure of a successful response when retrieving a project group permission. Includes group details and the assigned permission level. ```json { "type": "project_group_permission", "group": { "type": "group", "name": "Administrators", "slug": "administrators" }, "permission": "admin", "links": { "self": { "href": "https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/groups/administrators" } } } ``` -------------------------------- ### Project User Permissions Response Example Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-projects Example JSON response for listing project user permissions, showing user details and their permission level. ```json { "pagelen": 10, "values": [ { "type": "project_user_permission", "user": { "type": "user", "display_name": "Colin Cameron", "uuid": "{d301aafa-d676-4ee0-88be-962be7417567}", "account_id": "557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a" }, "permission": "admin", "links": { "self": { "href": "https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a" } } }, { "type": "project_user_permission", "user": { "type": "user", "display_name": "Sean Conaty", "uuid": "{504c3b62-8120-4f0c-a7bc-87800b9d6f70}", "account_id": "557058:ba8948b2-49da-43a9-9e8b-e7249b8e324c" }, "permission": "write", "links": { "self": { "href": "https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324c" } } } ], "page": 1, "size": 2 } ``` -------------------------------- ### Create Deploy Key Request Example Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-deployments This is a cURL command to create a deploy key. Replace placeholders like , {workspace}, and {repo_slug} with your specific values. ```bash curl --request POST \ --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/deploy-keys' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` -------------------------------- ### Example API Response with Links Section Source: https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-workspaces This example shows a Bitbucket API response containing a `links` section. Use the `repositories.href` value to construct repository URLs, which is the recommended approach for future-proofing your code. ```json { "links": { "repositories": { "href": "https://api.bitbucket.org/2.0/repositories/myworkspaceid" } ``` -------------------------------- ### Get a workspace webhook Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-workspaces Retrieves a specific webhook subscription installed on a workspace. Requires 'webhook' scope for OAuth/Connect apps or 'read:webhook:bitbucket' for API tokens. ```curl curl --request GET \ --url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/hooks/{uid}' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` -------------------------------- ### List Public Repositories (cURL) Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories Example using cURL to make a GET request to the deprecated /repositories endpoint to list public repositories. Requires an access token for authorization. ```curl curl --request GET \ --url 'https://api.bitbucket.org/2.0/repositories' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` -------------------------------- ### Example 200 OK Response for User Permission Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-projects This is an example of a successful response when retrieving a user's explicit permission for a project. It includes user details, the assigned permission level, and a link to the permission configuration. ```json { "type": "project_user_permission", "user": { "type": "user", "display_name": "Colin Cameron", "uuid": "{d301aafa-d676-4ee0-88be-962be7417567}", "account_id": "557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a" }, "permission": "admin", "links": { "self": { "href": "https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a" } } } ``` -------------------------------- ### Complete App Descriptor Source: https://developer.atlassian.com/cloud/bitbucket/app-descriptor This is a comprehensive example of an app descriptor file. It includes all essential fields and demonstrates how to define various modules for your Bitbucket app. ```json { "key": "example-app", "name": "Example App", "description": "An example app for Bitbucket", "vendor": { "name": "Angry Nerds", "url": "https://www.atlassian.com/angrynerds" }, "baseUrl": "https://example.com", "authentication": { "type": "jwt" }, "lifecycle": { "installed": "/installed", "uninstalled": "/uninstalled" }, "modules": { "oauthConsumer": { "clientId": "{{consumerKey}}" }, "webhooks": [ { "event": "pullrequest:created", "url": "/webhook" }, { "event": "pullrequest:updated", "url": "/webhook" }, { "event": "pullrequest:fulfilled", "url": "/webhook" } ], "webItems": [ { "url": "http://example.com?repoUuid={repository.uuid}", "name": { "value": "Example Web Item" }, "location": "org.bitbucket.repository.navigation", "key": "example-web-item", "params": { "auiIcon": "aui-iconfont-link" } } ], "repoPages": [ { "url": "/connect-example?repoUuid={repository.uuid}", "name": { "value": "Example Page" }, "location": "org.bitbucket.repository.navigation", "key": "example-repo-page", "params": { "auiIcon": "aui-iconfont-doc" } } ], "webPanels": [ { "url": "/connect-example?repoUuid={repository.uuid}", "name": { "value": "Example Web Panel" }, "location": "org.bitbucket.repository.overview.informationPanel", "key": "example-web-panel" } ] }, "scopes": ["account", "repository", "pullrequest"], "contexts": ["account"] } ``` -------------------------------- ### Get a webhook for a repository Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories Returns the webhook with the specified ID installed on the specified repository. Requires 'webhook' scope for OAuth 2.0/Connect apps or 'read:webhook:bitbucket' for API Tokens. ```APIDOC ## GET /repositories/{workspace}/{repo_slug}/hooks/{uid} ### Description Returns the webhook with the specified ID installed on the specified repository. ### Method GET ### Endpoint /repositories/{workspace}/{repo_slug}/hooks/{uid} ### Parameters #### Path Parameters - **workspace** (string) - Required - **repo_slug** (string) - Required - **uid** (string) - Required ### Responses #### Success Response (200 OK) - **Webhook Subscription** (object) - The webhook subscription object. ### Request Example ```curl curl --request GET \ --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/hooks/{uid}' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` ### Response Example ```json { "type": "", "uuid": "", "url": "", "description": "", "subject_type": "repository", "active": true, "created_at": "", "events": [ "issue:comment_created" ], "secret_set": true, "secret": "" } ``` ``` -------------------------------- ### Get Report Response Example Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-reports This JSON structure represents a successful response when retrieving a single commit report. It details the report's properties, including its type, ID, title, and associated data. ```json { "type": "", "uuid": "", "title": "", "details": "", "external_id": "", "reporter": "", "link": "", "remote_link_enabled": true, "logo_url": "", "report_type": "SECURITY", "result": "PASSED", "data": [ { "type": "BOOLEAN", "title": "", "value": {} } ], "created_on": "", "updated_on": "" } ``` -------------------------------- ### Retrieve Snippet (JSON) Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-snippets Example of retrieving a snippet using the `GET /snippets/{workspace}/{encoded_id}` endpoint with `Accept: application/json`. Requires `snippet` OAuth scope or `read:snippet:bitbucket` API Token scope. ```curl curl --request GET \ --url 'https://api.bitbucket.org/2.0/snippets/{workspace}/{encoded_id}' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` -------------------------------- ### Install URL for Registered Apps Source: https://developer.atlassian.com/cloud/bitbucket/install-an-app-from-your-site Use this format for the `href` attribute when creating an install button for registered Bitbucket Connect apps. It requires the app's `addon_key` and a `redirect_uri`. ```html https://bitbucket.org/site/addons/authorize?addon_key=&redirect_uri= ``` -------------------------------- ### Create Project Response Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-projects Example JSON response for a successfully created project. It includes details like type, links, UUID, key, owner, name, description, privacy status, and timestamps. ```json { "type": "", "links": { "html": { "href": "", "name": "" }, "avatar": { "href": "", "name": "" } }, "uuid": "", "key": "", "owner": { "type": "" }, "name": "", "description": "", "is_private": true, "created_on": "", "updated_on": "", "has_publicly_visible_repos": true } ``` -------------------------------- ### Configure OAuth Consumer and Callback URL Source: https://developer.atlassian.com/cloud/bitbucket/modules/oauth-consumer This example shows how to configure the baseUrl and callbackUrl for OAuth 2.0. The callback URL must start with the baseUrl for transparent access token retrieval from within your iframe's JavaScript. ```yaml baseUrl: https://foo.herokuapp.com/base callbackUrl: https://foo.herokuapp.com/base/oauth/callback ``` -------------------------------- ### Get Connect Addon Client Key for Forge App Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-addon Retrieve the client key of a Connect addon associated with a Forge app install via forgeAppId linkage. This is part of Connect -> Forge migration tooling and requires the `admin:workspace:bitbucket` scope. ```javascript api.asApp().requestBitbucket(route`/2.0/addon/{addon-key}/client-key`) ``` ```curl curl --request GET \ --url 'https://api.bitbucket.org/2.0/addon/{addon_key}/client-key' \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Linker Module Configuration Example Source: https://developer.atlassian.com/cloud/bitbucket/modules/linker This snippet shows a simplified descriptor for the linker module, defining a regular expression to match issue keys and a URL pattern to create links. ```json baseUrl: "https://jira.atlassian.com/", ... "modules": { linkers: [ { "key": "jira-url-linker", "regex": "([\w\-]+\-\d+)", "url": "/browse/\1", "type": "href" } ] } ``` -------------------------------- ### GET Get a snippet Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-snippets Retrieves a specific snippet by its UUID. ```APIDOC ## GET /snippets/{uuid} ### Description Retrieves a specific snippet by its UUID. ### Method GET ### Endpoint /snippets/{uuid} ### Parameters #### Path Parameters - **uuid** (string) - Required - The UUID of the snippet. ### Response #### Success Response (200) - **snippet** (object) - The snippet object. ``` -------------------------------- ### Create a Snippet with Metadata and Multiple Files Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-snippets This example demonstrates creating a snippet with metadata (title, privacy, SCM) and multiple files (foo.txt, image.png) using a multipart/related POST request. The JSON part describes the snippet, and subsequent parts contain the files. ```http POST /2.0/snippets/evzijst HTTP/1.1 Content-Length: 1188 Content-Type: multipart/related; start="snippet"; boundary="===============1438169132528273974==" MIME-Version: 1.0 --===============1438169132528273974== Content-Type: application/json; charset="utf-8" MIME-Version: 1.0 Content-ID: snippet { "title": "My snippet", "is_private": true, "scm": "git", "files": { "foo.txt": {}, "image.png": {} } } --===============1438169132528273974== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-ID: "foo.txt" Content-Disposition: attachment; filename="foo.txt" foo --===============1438169132528273974== Content-Type: image/png MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-ID: "image.png" Content-Disposition: attachment; filename="image.png" iVBORw0KGgoAAAANSUhEUgAAABQAAAAoCAYAAAD+MdrbAAABD0lEQVR4Ae3VMUoDQRTG8ccUaW2m TKONFxArJYJamCvkCnZTaa+VnQdJSBFl2SMsLFrEWNjZBZs0JgiL/+KrhhVmJRbCLPx4O+/DT2TB cbblJxf+UWFVVRNsEGAtgvJxnLm2H+A5RQ93uIl+3632PZyl/skjfOn9Gvdwmlcw5aPUwimG+NT5 EnNN036IaZePUuIcK533NVfal7/5yjWeot2z9ta1cAczHEf7I+3J0ws9Cgx0fsOFpmlfwKcWPuBQ 73Oc4FHzBaZ8llq4q1mr5B2mOUCt815qYR8eB1hG2VJ7j35q4RofaH7IG+Xrf/PfJhfmwtfFYoIN AqxFUD6OMxcvkO+UfKfkOyXfKdsv/AYCHMLVkHAFWgAAAABJRU5ErkJggg== --===============1438169132528273974==-- ``` -------------------------------- ### GET Get a comment on a snippet Source: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-snippets Retrieves a specific comment on a snippet. ```APIDOC ## GET /snippets/{uuid}/comments/{comment_id} ### Description Retrieves a specific comment on a snippet. ### Method GET ### Endpoint /snippets/{uuid}/comments/{comment_id} ### Parameters #### Path Parameters - **uuid** (string) - Required - The UUID of the snippet. - **comment_id** (integer) - Required - The ID of the comment. ### Response #### Success Response (200) - **comment** (object) - The comment object. ```