The REST API should be used as a last resort if your use case cannot be supported otherwise. Please reach out to us with your use case first.

This API is subject to change in future releases.

This documentation does not include all REST API endpoints. Please contact support if you need REST API access not documented here.

Authentication and basic parameters

Reference the Bitbucket REST API for Bitbucket’s built-in REST API, e.g. for querying lists of projects and repositories.

All requests use basic HTTP authentication. It is natively supported by most clients, such as python requests and curl.

All the URLs in the examples below are relative to the address of the Bitbucket Server instance.

If scanning a private repository (i.e. not part of a project), use ~username as the project-key parameter.

Disabling XRSF checks

Some of these API will fail by default if called from a host that is not part of the Bitbucket instance. To enable calling these APIs remotely, you may add the following header as documented here:

Example (python):

disable_xsrf_checks_header = {
    "X-Atlassian-Token": "no-check"
}
requests.get(url, auth=(username, password), headers=disable_xsrf_checks_header)
PY

Turning the security pre-receive hook on or off for a repository

To enable the security hook for a specific repository:

curl -u admin -X PUT http://localhost:7990/bitbucket/rest/api/latest/projects/PROJECT_1/repos/rep_1/settings/hooks/com.mohami.bitbucket.security-for-bitbucket:credentials-validation-hook/enabled

To disable the security hook for a specific repository:

curl -u admin -X DELETE http://localhost:7990/bitbucket/rest/api/latest/projects/PROJECT_1/repos/rep_1/settings/hooks/com.mohami.bitbucket.security-for-bitbucket:credentials-validation-hook/enabled

  • Replace “admin” with the username for a Bitbucket administrator

  • Replace “localhost:7990” with the hostname and port of your Bitbucket instance.

  • If your Bitbucket instance is served via HTTPS, update the command above to “https://” instead of “http://”.

  • Replace “PROJECT_1” and “rep_1” with the project and repository you’re interested in.

Fetching repository scan status

  • Method: GET

  • URL: /rest/security/1.0/scan/{project-key}/repos/{repository-key}

  • Parameters

    • branch: default repository branch used if omitted

    • includeWhitelisted: true to include failing lines which have been whitelisted.

    • rule: scan status for a specific rule. Overall scan status if omitted.

  • Response (JSON encoded):

    • scanKey: Unique key that can be used to refer to this scan, once subsequent scans are triggered

    • scanned (boolean): True if scan results are present for the branch

    • actual (boolean): True if scan results are for the latest commit on the branch, false if the branch has been updated since the last scan.

    • progress (int): Percentage progress, between 0 and 100.

    • running (boolean)

    • scheduled (boolean)

    • invalidLides: The list of vulnerabilities found. Only available once a scan has completed (scanned=true)

Example (python):

response = requests.get(f"{domain}/rest/security/1.0/scan/{project}/repos/{repo_key}",
                        auth=('username', 'password'))
response.raise_for_status()
scanned = response.json()['scanned']
up_to_date = response.json()['actual']
PY

Kicking off a new repository scan

  • Method: POST

  • URL: /rest/security/1.0/scan/{project-key}/repos/{repository-key}

  • Parameters

    • branch: default repository branch used if omitted

Example (python):

requests.post(f"{domain}/rest/security/1.0/scan/{project}/repos/{repo_key}?branch={branchName}",
                         auth=('username', 'password'))
PY

Cancelling a running or queued scan

  • Method: DELETE

  • URL: /rest/security/1.0/scan/{project-key}/repos/{repository-key}

  • Parameters

    • scanKey: identifier of the scan to cancel

Example (python):

requests.delete(f"{domain}/rest/security/1.0/scan/{project}/repos/{repo_key}?scanKey={scanKey}",
                         auth=('username', 'password'))
PY

Export scan results as CSV

  • Method: GET

  • URL: /rest/security/1.0/export-report/{project-key}/repos/{repository-key}

  • Parameters

    • branch: default repository branch used if omitted

    • includeWhitelisted: true to include failing lines which have been whitelisted.

    • ruleType: scan results for a specific rule. All rules included by default.

Example (python):

response = requests.get(f"{domain}/rest/security/1.0/export-report/{project_key}/repos/{repo_key}",
                        auth=creds)
response.raise_for_status()
with open('results.csv', 'w') as f:
    f.write(response.text)
PY

Fetching a list of all global rules

  • Method: GET

  • URL: /rest/security/1.0/rules

  • Response (JSON encoded):

    • List of rules. Each rule has the fields id, name, regexp, hardcoded, and enabled

      • hardcoded: this boolean will be “False” for custom rules. “True” for built-in rules

      • id: Unique identifier that can be used to refer to custom rules in other API endpoints

      • name: Display name of the rule.

      • regexp: Regular expression for the rule. Only available for custom rules.

Example (python):

response = requests.get(f"{domain}/rest/security/1.0/rules", auth=creds)
custom_rules = [x for x in response.json() if not x['hardcoded']]
PY

Fetch the names of all available rules for a specific repository

Due to the presence of custom mohami-config.yml files, some branches may have additional scan rules available in addition to the global ones. This API call returns the full list of rules for a specific branch of a specific repository.

  • Method: GET

  • URL: /rest/security/1.0/scan/{project-key}/rule_types/{repository-key}

  • Parameters

    • branch: default repository branch used if omitted.

  • Response (JSON encoded):

    • list of rule names. Disabled rules are also included.

Example (python):

response = requests.get(f"{domain}/rest/security/1.0/scan/{project}/rule_types/{repo_key}",
                        auth=creds, params={'branch': 'master'})
PY

Globally enabling a built-in rule

Rules can only be enabled or disabled globally (for all repositories) via the REST API. To disable or enable rules (or add custom rules) on a repository level, please update mohami-config.yml as documented here. This API requires Bitbucket administrator access.

  • Method: POST

  • URL: /rest/security/1.0/hardcoded/{rule-name}

  • Result: None. Enables the named rule globally.

response = requests.post(f"{domain}/rest/security/1.0/hardcoded/RSA", auth=creds)
PY

Globally disabling a built-in rule

Rules can only be enabled or disabled globally (for all repositories) via the REST API. To disable or enable rules (or add custom rules) on a repository level, please update mohami-config.yml as documented here. This API requires Bitbucket administrator access.

  • Method: DELETE

  • URL: /rest/security/1.0/hardcoded/{rule-name}

  • Result: None. Enables the named rule globally.

response = requests.delete(f"{domain}/rest/security/1.0/hardcoded/RSA", auth=creds)
PY