0
# Bitbucket API
1

2
Comprehensive Bitbucket REST API client providing access to repository management, pull requests, user administration, and project operations. Supports both Bitbucket Cloud and Server/Data Center platforms with 150+ public methods covering the complete Git repository lifecycle.
3

4
## Initialization
5

6
```python { .api }
7
class Bitbucket(AtlassianRestAPI):
8
    def __init__(self, url: str, username: str = None, password: str = None,
9
                 token: str = None, cloud: bool = None, **kwargs):
10
        """
11
        Initialize Bitbucket client.
12
        
13
        Parameters:
14
        - url (str): Base URL of Bitbucket instance
15
        - username (str, optional): Username for authentication
16
        - password (str, optional): Password or app password
17
        - token (str, optional): Bearer token for authentication
18
        - cloud (bool, optional): True for Cloud, False for Server/DC
19
        """
20
```
21

22
## Capabilities
23

24
### Repository Management
25

26
Core functionality for creating, managing, and configuring Git repositories with comprehensive metadata and settings control.
27

28
```python { .api }
29
def get_repositories(self, project_key: Optional[str] = None, start: int = 0,
30
                     limit: int = 25) -> T_resp_json:
31
    """
32
    Get repositories, optionally filtered by project.
33
    
34
    Parameters:
35
    - project_key: Filter by project key
36
    - start: Starting index for pagination
37
    - limit: Maximum results to return
38
    
39
    Returns:
40
    dict: Repository list with metadata
41
    """
42

43
def get_repository(self, project_key: str, repository_slug: str) -> T_resp_json:
44
    """
45
    Get repository details.
46
    
47
    Parameters:
48
    - project_key: Project key
49
    - repository_slug: Repository slug/name
50
    
51
    Returns:
52
    dict: Repository information with clone URLs and settings
53
    """
54

55
def create_repository(self, project_key: str, repository_name: str,
56
                      scm_id: str = "git", forkable: bool = True,
57
                      public: bool = False) -> T_resp_json:
58
    """
59
    Create new repository.
60
    
61
    Parameters:
62
    - project_key: Project key where repository will be created
63
    - repository_name: Repository name
64
    - scm_id: SCM type (default "git")
65
    - forkable: Allow forking
66
    - public: Make repository public
67
    
68
    Returns:
69
    dict: Created repository data with clone URLs
70
    """
71

72
def delete_repository(self, project_key: str, repository_slug: str) -> bool:
73
    """
74
    Delete repository.
75
    
76
    Parameters:
77
    - project_key: Project key
78
    - repository_slug: Repository slug
79
    
80
    Returns:
81
    bool: True if deletion successful
82
    """
83

84
def fork_repository(self, project_key: str, repository_slug: str,
85
                    new_project_key: str, new_repository_name: str) -> T_resp_json:
86
    """
87
    Fork repository to another project.
88
    
89
    Parameters:
90
    - project_key: Source project key
91
    - repository_slug: Source repository slug
92
    - new_project_key: Target project key
93
    - new_repository_name: New repository name
94
    
95
    Returns:
96
    dict: Forked repository data
97
    """
98
```
99

100
### Branch Management
101

102
```python { .api }
103
def get_branches(self, project_key: str, repository_slug: str,
104
                 base: Optional[str] = None, details: bool = True,
105
                 filter_text: Optional[str] = None, start: int = 0,
106
                 limit: int = 25) -> T_resp_json:
107
    """
108
    Get repository branches.
109
    
110
    Parameters:
111
    - project_key: Project key
112
    - repository_slug: Repository slug
113
    - base: Base branch for comparison
114
    - details: Include detailed branch information
115
    - filter_text: Filter branches by text
116
    - start: Starting index
117
    - limit: Maximum results
118
    
119
    Returns:
120
    dict: Branches list with commit info
121
    """
122

123
def create_branch(self, project_key: str, repository_slug: str,
124
                  name: str, start_point: str, message: Optional[str] = None) -> T_resp_json:
125
    """
126
    Create new branch.
127
    
128
    Parameters:
129
    - project_key: Project key
130
    - repository_slug: Repository slug
131
    - name: New branch name
132
    - start_point: Starting commit hash or branch name
133
    - message: Commit message for branch creation
134
    
135
    Returns:
136
    dict: Created branch information
137
    """
138

139
def delete_branch(self, project_key: str, repository_slug: str,
140
                  name: str, end_point: str) -> bool:
141
    """
142
    Delete branch.
143
    
144
    Parameters:
145
    - project_key: Project key
146
    - repository_slug: Repository slug
147
    - name: Branch name to delete
148
    - end_point: End point commit hash
149
    
150
    Returns:
151
    bool: True if deletion successful
152
    """
153

154
def set_default_branch(self, project_key: str, repository_slug: str,
155
                       ref: str) -> T_resp_json:
156
    """
157
    Set default branch.
158
    
159
    Parameters:
160
    - project_key: Project key
161
    - repository_slug: Repository slug
162
    - ref: Branch reference to set as default
163
    
164
    Returns:
165
    dict: Updated default branch information
166
    """
167
```
168

169
### Pull Request Management
170

171
```python { .api }
172
def get_pull_requests(self, project_key: str, repository_slug: str,
173
                      state: str = "OPEN", order: str = "NEWEST",
174
                      start: int = 0, limit: int = 25) -> T_resp_json:
175
    """
176
    Get pull requests.
177
    
178
    Parameters:
179
    - project_key: Project key
180
    - repository_slug: Repository slug
181
    - state: PR state ("OPEN", "MERGED", "DECLINED", "ALL")
182
    - order: Sort order ("NEWEST", "OLDEST")
183
    - start: Starting index
184
    - limit: Maximum results
185
    
186
    Returns:
187
    dict: Pull requests list with details
188
    """
189

190
def get_pull_request(self, project_key: str, repository_slug: str,
191
                     pull_request_id: int) -> T_resp_json:
192
    """
193
    Get pull request details.
194
    
195
    Parameters:
196
    - project_key: Project key
197
    - repository_slug: Repository slug
198
    - pull_request_id: Pull request ID
199
    
200
    Returns:
201
    dict: Pull request information with participants and reviewers
202
    """
203

204
def create_pull_request(self, project_key: str, repository_slug: str,
205
                        title: str, description: str, from_ref: str,
206
                        to_ref: str, reviewers: Optional[List[str]] = None) -> T_resp_json:
207
    """
208
    Create pull request.
209
    
210
    Parameters:
211
    - project_key: Project key
212
    - repository_slug: Repository slug
213
    - title: Pull request title
214
    - description: Pull request description
215
    - from_ref: Source branch reference
216
    - to_ref: Target branch reference
217
    - reviewers: List of reviewer usernames
218
    
219
    Returns:
220
    dict: Created pull request data
221
    """
222

223
def update_pull_request(self, project_key: str, repository_slug: str,
224
                        pull_request_id: int, title: str, description: str,
225
                        version: int) -> T_resp_json:
226
    """
227
    Update pull request.
228
    
229
    Parameters:
230
    - project_key: Project key
231
    - repository_slug: Repository slug
232
    - pull_request_id: Pull request ID
233
    - title: New title
234
    - description: New description
235
    - version: Current version (for optimistic locking)
236
    
237
    Returns:
238
    dict: Updated pull request data
239
    """
240

241
def merge_pull_request(self, project_key: str, repository_slug: str,
242
                       pull_request_id: int, version: int) -> T_resp_json:
243
    """
244
    Merge pull request.
245
    
246
    Parameters:
247
    - project_key: Project key
248
    - repository_slug: Repository slug
249
    - pull_request_id: Pull request ID
250
    - version: Current version
251
    
252
    Returns:
253
    dict: Merge result information
254
    """
255

256
def decline_pull_request(self, project_key: str, repository_slug: str,
257
                         pull_request_id: int, version: int) -> T_resp_json:
258
    """
259
    Decline pull request.
260
    
261
    Parameters:
262
    - project_key: Project key
263
    - repository_slug: Repository slug
264
    - pull_request_id: Pull request ID
265
    - version: Current version
266
    
267
    Returns:
268
    dict: Declined pull request data
269
    """
270
```
271

272
### User and Group Management
273

274
```python { .api }
275
def get_users(self, filter_text: Optional[str] = None, start: int = 0,
276
              limit: int = 25) -> T_resp_json:
277
    """
278
    Get users.
279
    
280
    Parameters:
281
    - filter_text: Filter users by text
282
    - start: Starting index
283
    - limit: Maximum results
284
    
285
    Returns:
286
    dict: Users list with profile information
287
    """
288

289
def get_user(self, username: str) -> T_resp_json:
290
    """
291
    Get user details.
292
    
293
    Parameters:
294
    - username: Username to retrieve
295
    
296
    Returns:
297
    dict: User profile information
298
    """
299

300
def create_user(self, username: str, password: str, display_name: str,
301
                email_address: str) -> T_resp_json:
302
    """
303
    Create user (Server/DC only).
304
    
305
    Parameters:
306
    - username: Unique username
307
    - password: User password
308
    - display_name: Display name
309
    - email_address: Email address
310
    
311
    Returns:
312
    dict: Created user data
313
    """
314

315
def get_groups(self, filter_text: Optional[str] = None, start: int = 0,
316
               limit: int = 25) -> T_resp_json:
317
    """
318
    Get groups.
319
    
320
    Parameters:
321
    - filter_text: Filter groups by text
322
    - start: Starting index
323
    - limit: Maximum results
324
    
325
    Returns:
326
    dict: Groups list
327
    """
328

329
def group_members(self, group_name: str, start: int = 0, limit: int = 25) -> T_resp_json:
330
    """
331
    Get group members.
332
    
333
    Parameters:
334
    - group_name: Group name
335
    - start: Starting index
336
    - limit: Maximum results
337
    
338
    Returns:
339
    dict: Group members list
340
    """
341

342
def add_user_to_group(self, username: str, group_name: str) -> T_resp_json:
343
    """
344
    Add user to group.
345
    
346
    Parameters:
347
    - username: Username to add
348
    - group_name: Target group name
349
    
350
    Returns:
351
    dict: Operation result
352
    """
353
```
354

355
### Project Management
356

357
```python { .api }
358
def project_list(self, start: int = 0, limit: int = 25) -> T_resp_json:
359
    """
360
    Get all projects.
361
    
362
    Parameters:
363
    - start: Starting index
364
    - limit: Maximum results
365
    
366
    Returns:
367
    dict: Projects list with metadata
368
    """
369

370
def get_project(self, project_key: str) -> T_resp_json:
371
    """
372
    Get project details.
373
    
374
    Parameters:
375
    - project_key: Project key
376
    
377
    Returns:
378
    dict: Project information with repositories and permissions
379
    """
380

381
def create_project(self, project_key: str, project_name: str,
382
                   description: Optional[str] = None) -> T_resp_json:
383
    """
384
    Create project.
385
    
386
    Parameters:
387
    - project_key: Unique project key
388
    - project_name: Project display name
389
    - description: Project description
390
    
391
    Returns:
392
    dict: Created project data
393
    """
394

395
def all_project_administrators(self, project_key: str) -> List[dict]:
396
    """
397
    Get project administrators.
398
    
399
    Parameters:
400
    - project_key: Project key
401
    
402
    Returns:
403
    List[dict]: Project administrators list
404
    """
405

406
def get_project_users(self, project_key: str, filter_text: Optional[str] = None,
407
                       start: int = 0, limit: int = 25) -> T_resp_json:
408
    """
409
    Get project users.
410
    
411
    Parameters:
412
    - project_key: Project key
413
    - filter_text: Filter users by text
414
    - start: Starting index
415
    - limit: Maximum results
416
    
417
    Returns:
418
    dict: Project users with permissions
419
    """
420
```
421

422
### Webhook Management
423

424
```python { .api }
425
def get_webhooks(self, project_key: str, repository_slug: str) -> List[dict]:
426
    """
427
    Get repository webhooks.
428
    
429
    Parameters:
430
    - project_key: Project key
431
    - repository_slug: Repository slug
432
    
433
    Returns:
434
    List[dict]: Configured webhooks
435
    """
436

437
def create_webhook(self, project_key: str, repository_slug: str,
438
                   name: str, url: str, events: List[str],
439
                   active: bool = True) -> T_resp_json:
440
    """
441
    Create webhook.
442
    
443
    Parameters:
444
    - project_key: Project key
445
    - repository_slug: Repository slug
446
    - name: Webhook name
447
    - url: Webhook URL
448
    - events: List of events to trigger on
449
    - active: Enable webhook immediately
450
    
451
    Returns:
452
    dict: Created webhook data
453
    """
454

455
def update_webhook(self, project_key: str, repository_slug: str,
456
                   webhook_id: str, name: str, url: str, events: List[str],
457
                   active: bool = True) -> T_resp_json:
458
    """
459
    Update webhook.
460
    
461
    Parameters:
462
    - project_key: Project key
463
    - repository_slug: Repository slug
464
    - webhook_id: Webhook ID to update
465
    - name: New webhook name
466
    - url: New webhook URL
467
    - events: New events list
468
    - active: Enable/disable webhook
469
    
470
    Returns:
471
    dict: Updated webhook data
472
    """
473

474
def delete_webhook(self, project_key: str, repository_slug: str,
475
                   webhook_id: str) -> bool:
476
    """
477
    Delete webhook.
478
    
479
    Parameters:
480
    - project_key: Project key
481
    - repository_slug: Repository slug
482
    - webhook_id: Webhook ID to delete
483
    
484
    Returns:
485
    bool: True if deletion successful
486
    """
487
```
488

489
### System Administration
490

491
```python { .api }
492
def get_system_information(self) -> T_resp_json:
493
    """
494
    Get system information.
495
    
496
    Returns:
497
    dict: System version and build information
498
    """
499

500
def reindex(self) -> T_resp_json:
501
    """
502
    Trigger system reindex.
503
    
504
    Returns:
505
    dict: Reindex status
506
    """
507

508
def check_reindexing_status(self) -> T_resp_json:
509
    """
510
    Check reindexing status.
511
    
512
    Returns:
513
    dict: Current reindex progress
514
    """
515

516
def get_license_information(self) -> T_resp_json:
517
    """
518
    Get license information.
519
    
520
    Returns:
521
    dict: License details and user counts
522
    """
523
```
524

525
## Usage Examples
526

527
### Repository Operations
528

529
```python
530
from atlassian import Bitbucket
531

532
bitbucket = Bitbucket(
533
    url="https://bitbucket.your-company.com",
534
    username="username",
535
    password="password"
536
)
537

538
# Create repository
539
repo = bitbucket.create_repository(
540
    project_key="PROJ",
541
    repository_name="my-new-repo",
542
    public=False
543
)
544

545
# Get repository info
546
repo_info = bitbucket.get_repository("PROJ", "my-new-repo")
547

548
# Get all repositories
549
repos = bitbucket.get_repositories(project_key="PROJ")
550
```
551

552
### Branch Management
553

554
```python
555
# Get branches
556
branches = bitbucket.get_branches("PROJ", "my-repo")
557

558
# Create feature branch
559
feature_branch = bitbucket.create_branch(
560
    "PROJ", "my-repo",
561
    name="feature/new-feature",
562
    start_point="refs/heads/develop"
563
)
564

565
# Set default branch
566
bitbucket.set_default_branch(
567
    "PROJ", "my-repo",
568
    ref="refs/heads/main"
569
)
570
```
571

572
### Pull Request Workflow
573

574
```python
575
# Create pull request
576
pr = bitbucket.create_pull_request(
577
    project_key="PROJ",
578
    repository_slug="my-repo",
579
    title="Add new feature",
580
    description="This PR adds the new feature requested in PROJ-123",
581
    from_ref="refs/heads/feature/new-feature",
582
    to_ref="refs/heads/develop",
583
    reviewers=["john.doe", "jane.smith"]
584
)
585

586
# Get pull requests
587
prs = bitbucket.get_pull_requests(
588
    "PROJ", "my-repo",
589
    state="OPEN"
590
)
591

592
# Merge pull request
593
merge_result = bitbucket.merge_pull_request(
594
    "PROJ", "my-repo",
595
    pull_request_id=pr["id"],
596
    version=pr["version"]
597
)
598
```
599

600
### User and Project Management
601

602
```python
603
# Get users
604
users = bitbucket.get_users(filter_text="john")
605

606
# Create project
607
project = bitbucket.create_project(
608
    project_key="NEWPROJ",
609
    project_name="New Project",
610
    description="Project for new initiative"
611
)
612

613
# Get project details
614
project_info = bitbucket.get_project("PROJ")
615
admins = bitbucket.all_project_administrators("PROJ")
616
```
617

618
### Webhook Configuration
619

620
```python
621
# Create webhook for CI/CD
622
webhook = bitbucket.create_webhook(
623
    project_key="PROJ",
624
    repository_slug="my-repo",
625
    name="CI Build Trigger",
626
    url="https://ci.company.com/bitbucket-webhook",
627
    events=["repo:refs_changed", "pr:opened", "pr:merged"],
628
    active=True
629
)
630

631
# Get webhooks
632
webhooks = bitbucket.get_webhooks("PROJ", "my-repo")
633
```
634

635
## Error Handling
636

637
```python
638
from atlassian.errors import ApiNotFoundError, ApiPermissionError
639

640
try:
641
    repo = bitbucket.get_repository("INVALID", "nonexistent")
642
except ApiNotFoundError:
643
    print("Repository not found")
644
except ApiPermissionError:
645
    print("Permission denied")
646
```
647

648
## Types
649

650
```python { .api }
651
from atlassian.typehints import T_id, T_resp_json
652
from typing import List, Dict, Optional
653

654
# Common parameter types
655
ProjectKey = str
656
RepositorySlug = str
657
BranchName = str
658
PullRequestState = str  # "OPEN", "MERGED", "DECLINED", "ALL"
659
WebhookEvent = str  # "repo:refs_changed", "pr:opened", etc.
660
```