> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket

> Give agents authenticated access to the Bitbucket Cloud REST API.

The `@guildai-services/guildai~bitbucket` package provides agents with access to the Bitbucket Cloud REST API through Guild's OAuth 2.0 integration.

## Authentication

* **Type:** OAuth 2.0
* **Token expiration:** 1 hour (auto-refreshed)
* **Note:** Only Bitbucket Cloud is supported — not Bitbucket Server or Data Center

### Setup

<Steps>
  <Step title="Open Credentials">Go to **Credentials** in Guild.</Step>
  <Step title="Connect Bitbucket">Click **Bitbucket** and authorize Guild to access your account.</Step>
  <Step title="Grant access">Select the workspaces and repositories to authorize.</Step>
</Steps>

## Usage

```typescript theme={null}
import { bitbucketTools } from "@guildai-services/guildai~bitbucket"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Bitbucket pull requests",
  tools: { ...bitbucketTools },
})
```

### Selecting specific tools

Agents perform better with fewer tools. Use `pick()` to include only what your agent needs. Tools are named with the `bitbucket_` prefix.

```typescript theme={null}
import { bitbucketTools } from "@guildai-services/guildai~bitbucket"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Bitbucket pull requests",
  tools: {
    ...pick(bitbucketTools, [
      "bitbucket_get_repositories_workspace_repo_slug_pullrequests",
      "bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id",
      "bitbucket_post_repositories_workspace_repo_slug_pullrequests",
      "bitbucket_post_repositories_workspace_repo_slug_pullrequests_pull_request_id_merge",
    ]),
  },
})
```

## API endpoints

<AccordionGroup>
  <Accordion title="Workspaces">
    | Operation                            | Method | Path                               |
    | ------------------------------------ | ------ | ---------------------------------- |
    | `get_workspaces`                     | GET    | `/workspaces`                      |
    | `get_workspaces_workspace`           | GET    | `/workspaces/{workspace}`          |
    | `get_workspaces_workspace_members`   | GET    | `/workspaces/{workspace}/members`  |
    | `get_workspaces_workspace_projects`  | GET    | `/workspaces/{workspace}/projects` |
    | `post_workspaces_workspace_projects` | POST   | `/workspaces/{workspace}/projects` |
  </Accordion>

  <Accordion title="Repositories">
    | Operation                                 | Method | Path                                    |
    | ----------------------------------------- | ------ | --------------------------------------- |
    | `get_repositories_workspace`              | GET    | `/repositories/{workspace}`             |
    | `get_repositories_workspace_repo_slug`    | GET    | `/repositories/{workspace}/{repo_slug}` |
    | `post_repositories_workspace_repo_slug`   | POST   | `/repositories/{workspace}/{repo_slug}` |
    | `put_repositories_workspace_repo_slug`    | PUT    | `/repositories/{workspace}/{repo_slug}` |
    | `delete_repositories_workspace_repo_slug` | DELETE | `/repositories/{workspace}/{repo_slug}` |
  </Accordion>

  <Accordion title="Branches">
    | Operation                                                    | Method | Path                                                         |
    | ------------------------------------------------------------ | ------ | ------------------------------------------------------------ |
    | `get_repositories_workspace_repo_slug_refs_branches`         | GET    | `/repositories/{workspace}/{repo_slug}/refs/branches`        |
    | `post_repositories_workspace_repo_slug_refs_branches`        | POST   | `/repositories/{workspace}/{repo_slug}/refs/branches`        |
    | `get_repositories_workspace_repo_slug_refs_branches_name`    | GET    | `/repositories/{workspace}/{repo_slug}/refs/branches/{name}` |
    | `delete_repositories_workspace_repo_slug_refs_branches_name` | DELETE | `/repositories/{workspace}/{repo_slug}/refs/branches/{name}` |
  </Accordion>

  <Accordion title="Commits">
    | Operation                                                      | Method | Path                                                             |
    | -------------------------------------------------------------- | ------ | ---------------------------------------------------------------- |
    | `get_repositories_workspace_repo_slug_commits`                 | GET    | `/repositories/{workspace}/{repo_slug}/commits`                  |
    | `get_repositories_workspace_repo_slug_commit_commit`           | GET    | `/repositories/{workspace}/{repo_slug}/commit/{commit}`          |
    | `get_repositories_workspace_repo_slug_commit_commit_statuses`  | GET    | `/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses` |
    | `get_repositories_workspace_repo_slug_commit_commit_comments`  | GET    | `/repositories/{workspace}/{repo_slug}/commit/{commit}/comments` |
    | `post_repositories_workspace_repo_slug_commit_commit_comments` | POST   | `/repositories/{workspace}/{repo_slug}/commit/{commit}/comments` |
  </Accordion>

  <Accordion title="Pull requests">
    | Operation                                                                     | Method | Path                                                                            |
    | ----------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------- |
    | `get_repositories_workspace_repo_slug_pullrequests`                           | GET    | `/repositories/{workspace}/{repo_slug}/pullrequests`                            |
    | `post_repositories_workspace_repo_slug_pullrequests`                          | POST   | `/repositories/{workspace}/{repo_slug}/pullrequests`                            |
    | `get_repositories_workspace_repo_slug_pullrequests_pull_request_id`           | GET    | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}`          |
    | `put_repositories_workspace_repo_slug_pullrequests_pull_request_id`           | PUT    | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}`          |
    | `post_repositories_workspace_repo_slug_pullrequests_pull_request_id_approve`  | POST   | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/approve`  |
    | `post_repositories_workspace_repo_slug_pullrequests_pull_request_id_merge`    | POST   | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge`    |
    | `post_repositories_workspace_repo_slug_pullrequests_pull_request_id_decline`  | POST   | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/decline`  |
    | `get_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments`  | GET    | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments` |
    | `post_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments` | POST   | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments` |
    | `get_repositories_workspace_repo_slug_pullrequests_pull_request_id_commits`   | GET    | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/commits`  |
    | `get_repositories_workspace_repo_slug_pullrequests_pull_request_id_diff`      | GET    | `/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/diff`     |
  </Accordion>

  <Accordion title="Issues">
    | Operation                                                        | Method | Path                                                               |
    | ---------------------------------------------------------------- | ------ | ------------------------------------------------------------------ |
    | `get_repositories_workspace_repo_slug_issues`                    | GET    | `/repositories/{workspace}/{repo_slug}/issues`                     |
    | `post_repositories_workspace_repo_slug_issues`                   | POST   | `/repositories/{workspace}/{repo_slug}/issues`                     |
    | `get_repositories_workspace_repo_slug_issues_issue_id`           | GET    | `/repositories/{workspace}/{repo_slug}/issues/{issue_id}`          |
    | `put_repositories_workspace_repo_slug_issues_issue_id`           | PUT    | `/repositories/{workspace}/{repo_slug}/issues/{issue_id}`          |
    | `delete_repositories_workspace_repo_slug_issues_issue_id`        | DELETE | `/repositories/{workspace}/{repo_slug}/issues/{issue_id}`          |
    | `get_repositories_workspace_repo_slug_issues_issue_id_comments`  | GET    | `/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments` |
    | `post_repositories_workspace_repo_slug_issues_issue_id_comments` | POST   | `/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments` |
  </Accordion>

  <Accordion title="Source & diffs">
    | Operation                                              | Method | Path                                                        |
    | ------------------------------------------------------ | ------ | ----------------------------------------------------------- |
    | `get_repositories_workspace_repo_slug_src`             | GET    | `/repositories/{workspace}/{repo_slug}/src`                 |
    | `get_repositories_workspace_repo_slug_src_commit_path` | GET    | `/repositories/{workspace}/{repo_slug}/src/{commit}/{path}` |
    | `get_repositories_workspace_repo_slug_diff_spec`       | GET    | `/repositories/{workspace}/{repo_slug}/diff/{spec}`         |
    | `get_repositories_workspace_repo_slug_diffstat_spec`   | GET    | `/repositories/{workspace}/{repo_slug}/diffstat/{spec}`     |
  </Accordion>
</AccordionGroup>

## Webhook events

Bitbucket uses a trigger-scoped webhook model — each trigger gets its own dedicated webhook with a unique secret.

| Event                         | Description                       |
| ----------------------------- | --------------------------------- |
| `issue:created`               | Issue created                     |
| `issue:updated`               | Issue updated                     |
| `pullrequest:created`         | Pull request created              |
| `pullrequest:updated`         | Pull request updated              |
| `pullrequest:approved`        | Pull request approved             |
| `pullrequest:fulfilled`       | Pull request merged               |
| `pullrequest:rejected`        | Pull request declined             |
| `pullrequest:comment_created` | Comment created on a pull request |
| `repo:push`                   | Commits pushed to a repository    |
| `repo:commit_status_created`  | Commit status created             |
| `repo:commit_status_updated`  | Commit status updated             |

Triggers require a `workspace_slug` and optionally a `repo_slug` to scope webhooks to a specific workspace or repository.

## Package version

The `@guildai-services/guildai~bitbucket` package is on the 2.x release line. The 2.x package is a code-generated client built directly from Bitbucket's OpenAPI specification, replacing the hand-maintained 1.x package.

If you are migrating an agent that was written against the 1.x package, review your tool names — some operation identifiers changed between versions. All operations follow the same `bitbucket_<method>_<path>` naming convention as before, but paths may have been normalized.

## Limitations

* Only Bitbucket Cloud is supported (not Bitbucket Server or Data Center)
* Each trigger creates a separate webhook on the repository