0
# Atlassian Python API
1

2
A comprehensive Python library providing simple and convenient access to Atlassian products including Jira (Software and Service Management), Confluence, Bitbucket, Bamboo, and specialized apps like Insight (CMDB) and X-Ray (Test Management). Built on official REST APIs with additional support for private methods and protocols, enabling automation, system integration, and custom applications that extend Atlassian product functionality across both Server and Cloud instances.
3

4
## Package Information
5

6
- **Package Name**: atlassian-python-api
7
- **Language**: Python
8
- **Installation**: `pip install atlassian-python-api`
9
- **Python Support**: 3.9, 3.10, 3.11, 3.12, 3.13
10
- **License**: Apache-2.0
11

12
## Core Imports
13

14
```python
15
from atlassian import (
16
    Jira, Confluence, Bitbucket,
17
    ServiceDesk, Bamboo, Xray,
18
    Insight, Assets, AssetsCloud,
19
    Portfolio, Crowd, CloudAdminOrgs, CloudAdminUsers,
20
    MarketPlace, StatusPage
21
)
22
```
23

24
Import specific products:
25

26
```python
27
from atlassian import Jira, Confluence
28
```
29

30
## Basic Usage
31

32
```python
33
from atlassian import Jira, Confluence
34

35
# Initialize connections with authentication
36
jira = Jira(
37
    url="https://your-domain.atlassian.net",
38
    username="your-email@example.com",
39
    password="your-api-token"
40
)
41

42
confluence = Confluence(
43
    url="https://your-domain.atlassian.net",
44
    username="your-email@example.com", 
45
    password="your-api-token"
46
)
47

48
# Work with Jira issues
49
issue = jira.issue("PROJ-123")
50
new_issue = jira.create_issue(
51
    project="PROJ",
52
    summary="New feature request",
53
    description="Detailed description",
54
    issuetype="Story"
55
)
56

57
# Work with Confluence pages
58
page = confluence.get_page_by_title("Space Key", "Page Title")
59
confluence.create_page(
60
    space="SPACE",
61
    title="New Page",
62
    body="<p>Page content in storage format</p>"
63
)
64

65
# Work with Bitbucket repositories
66
bitbucket = Bitbucket(
67
    url="https://bitbucket.your-company.com",
68
    username="username",
69
    password="password"
70
)
71
repos = bitbucket.get_repositories()
72

73
# Work with StatusPage incidents
74
statuspage = StatusPage(url="https://api.statuspage.io", token="api-token")
75
incident = statuspage.page_create_incident(page_id, {
76
    "name": "Service Degradation",
77
    "status": "investigating",
78
    "impact": "minor"
79
})
80
```
81

82
## Architecture
83

84
The library is organized around product-specific client classes that inherit from a common `AtlassianRestAPI` base class:
85

86
- **Product Clients**: Each Atlassian product has a dedicated client class (Jira, Confluence, etc.)
87
- **Base Infrastructure**: Common REST client functionality, authentication, error handling
88
- **Type Safety**: Comprehensive type definitions and error classes for robust integration
89
- **Authentication**: Support for Basic Auth, OAuth, API Tokens, and Kerberos
90
- **Flexibility**: Raw HTTP access alongside high-level convenience methods
91

92
## Capabilities
93

94
### Core Product APIs
95

96
Primary interfaces to Atlassian's main products with comprehensive functionality covering all aspects of each platform.
97

98
```python { .api }
99
class Jira(AtlassianRestAPI):
100
    def __init__(self, url: str, *args, **kwargs): ...
101
    def issue(self, key: str) -> dict: ...
102
    def create_issue(self, project: str, summary: str, description: str = "", 
103
                    issuetype: str = "Task", **kwargs) -> dict: ...
104
    def projects(self) -> List[dict]: ...
105
    def search_users(self, query: str) -> List[dict]: ...
106

107
class Confluence(AtlassianRestAPI):
108
    def __init__(self, url: str, *args, **kwargs): ...
109
    def get_page_by_title(self, space: str, title: str) -> dict: ...
110
    def create_page(self, space: str, title: str, body: str, 
111
                   parent_id: Optional[str] = None) -> dict: ...
112
    def get_all_spaces(self) -> List[dict]: ...
113

114
class Bitbucket(AtlassianRestAPI):
115
    def __init__(self, url: str, *args, **kwargs): ...
116
    def get_repositories(self) -> List[dict]: ...
117
    def create_repository(self, project_key: str, repository_name: str) -> dict: ...
118
    def get_pull_requests(self, project_key: str, repository_slug: str) -> List[dict]: ...
119
```
120

121
[Jira API](./jira.md) | [Confluence API](./confluence.md) | [Bitbucket API](./bitbucket.md)
122

123
### Service Management
124

125
Comprehensive service desk and customer support functionality through Jira Service Management integration.
126

127
```python { .api }
128
class ServiceDesk(AtlassianRestAPI):
129
    def __init__(self, url: str, *args, **kwargs): ...
130
    def get_service_desks(self) -> List[dict]: ...
131
    def create_customer_request(self, service_desk_id: str, request_type_id: str,
132
                               summary: str, description: str = "") -> dict: ...
133
    def get_customer_requests(self, service_desk_id: str) -> List[dict]: ...
134
```
135

136
[Service Management](./service-management.md)
137

138
### Development Tools
139

140
CI/CD build management with Bamboo and comprehensive test management through X-Ray integration.
141

142
```python { .api }
143
class Bamboo(AtlassianRestAPI):
144
    def __init__(self, url: str, *args, **kwargs): ...
145
    def get_builds(self) -> List[dict]: ...
146
    def start_build(self, plan_key: str) -> dict: ...
147
    def get_results(self, plan_key: str) -> List[dict]: ...
148

149
class Xray(AtlassianRestAPI):
150
    def __init__(self, url: str, *args, **kwargs): ...
151
    def get_tests(self, project_key: str) -> List[dict]: ...
152
    def get_test_runs(self, test_key: str) -> List[dict]: ...
153
    def import_execution_results(self, execution_results: dict) -> dict: ...
154
```
155

156
[Development Tools](./development-tools.md)
157

158
### Asset Management
159

160
Comprehensive asset and configuration management through Insight CMDB and Portfolio planning capabilities.
161

162
```python { .api }
163
class Insight(AtlassianRestAPI):
164
    def __init__(self, url: str, *args, **kwargs): ...
165
    def get_object(self, object_id: str) -> dict: ...
166
    def create_object(self, object_type_id: str, attributes: dict) -> dict: ...
167
    def get_object_schemas(self) -> List[dict]: ...
168

169
class AssetsCloud(AtlassianRestAPI):
170
    def __init__(self, url: str, *args, **kwargs): ...
171
    def get_workspaces(self) -> List[dict]: ...
172
    def get_objects(self, workspace_id: str) -> List[dict]: ...
173

174
class Portfolio(AtlassianRestAPI):
175
    def __init__(self, url: str, *args, **kwargs): ...
176
    def get_plans(self) -> List[dict]: ...
177
    def create_plan(self, name: str, description: str = "") -> dict: ...
178
```
179

180
[Asset Management](./asset-management.md)
181

182
### Status Communication
183

184
Comprehensive incident management, status communication, and service reliability monitoring through StatusPage integration for transparent service communication.
185

186
```python { .api }
187
class StatusPage(AtlassianRestAPI):
188
    def __init__(self, url: str, *args, **kwargs): ...
189
    def page_list_pages(self) -> List[dict]: ...
190
    def page_create_incident(self, page_id: str, incident: dict) -> dict: ...
191
    def page_get_components(self, page_id: str) -> dict: ...
192
    def page_create_subscriber(self, page_id: str, subscriber: dict) -> dict: ...
193
    def page_add_data_to_metric(self, page_id: str, metric_id: str, data: dict) -> dict: ...
194
```
195

196
[StatusPage](./statuspage.md)
197

198
### User Management & Administration
199

200
User directory management, cloud administration, and marketplace integration for comprehensive Atlassian ecosystem management.
201

202
```python { .api }
203
class Crowd(AtlassianRestAPI):
204
    def __init__(self, url: str, *args, **kwargs): ...
205
    def get_users(self) -> List[dict]: ...
206
    def create_user(self, username: str, email: str, first_name: str, 
207
                   last_name: str) -> dict: ...
208
    def authenticate_user(self, username: str, password: str) -> bool: ...
209

210
class CloudAdminOrgs(AtlassianRestAPI):
211
    def __init__(self, url: str, *args, **kwargs): ...
212
    def get_orgs(self) -> List[dict]: ...
213
    def get_org_users(self, org_id: str) -> List[dict]: ...
214

215
class MarketPlace(AtlassianRestAPI):
216
    def __init__(self, url: str, *args, **kwargs): ...
217
    def get_addon_info(self, addon_key: str) -> dict: ...
218
```
219

220
[Administration](./administration.md)
221

222
## Base Infrastructure
223

224
### Authentication
225

226
The library supports multiple authentication methods:
227

228
```python { .api }
229
# API Token (recommended for Cloud)
230
client = Jira(
231
    url="https://your-domain.atlassian.net",
232
    username="email@example.com",
233
    password="api-token"
234
)
235

236
# OAuth 1.0a
237
client = Jira(
238
    url="https://your-domain.atlassian.net",
239
    oauth={
240
        "access_token": "token",
241
        "access_token_secret": "secret",
242
        "consumer_key": "key",
243
        "key_cert": "private_key"
244
    }
245
)
246

247
# Basic Authentication (Server instances)
248
client = Jira(
249
    url="https://jira.company.com",
250
    username="username",
251
    password="password"
252
)
253
```
254

255
### Error Handling
256

257
Complete exception hierarchy for robust error handling and debugging.
258

259
```python { .api }
260
from atlassian.errors import (
261
    ApiError, ApiNotFoundError, ApiPermissionError,
262
    ApiValueError, ApiConflictError, ApiNotAcceptable,
263
    JsonRPCError, JsonRPCRestrictionsError
264
)
265

266
class ApiError(Exception):
267
    """Base exception for all API errors with reason attribute"""
268
    def __init__(self, *args, reason=None): ...
269

270
class ApiNotFoundError(ApiError):
271
    """HTTP 404 - Resource not found"""
272
    pass
273

274
class ApiPermissionError(ApiError):
275
    """HTTP 403 - Permission denied or authentication failed"""
276
    pass
277

278
class ApiValueError(ApiError):
279
    """HTTP 400 - Invalid request parameters or malformed data"""
280
    pass
281

282
class ApiConflictError(ApiError):
283
    """HTTP 409 - Resource conflict (e.g., duplicate names)"""
284
    pass
285

286
class ApiNotAcceptable(ApiError):
287
    """HTTP 406 - Request format not acceptable"""
288
    pass
289

290
class JsonRPCError(Exception):
291
    """Base exception for JSON-RPC specific errors"""
292
    pass
293

294
class JsonRPCRestrictionsError(JsonRPCError):
295
    """JSON-RPC permission or access restrictions"""
296
    pass
297

298
try:
299
    issue = jira.issue("INVALID-123")
300
except ApiNotFoundError:
301
    print("Issue not found")
302
except ApiPermissionError:
303
    print("Permission denied")
304
except ApiValueError as e:
305
    print(f"Invalid request: {e}")
306
except ApiError as e:
307
    print(f"API error {e.reason}: {e}")
308
```
309

310
### Base REST Client
311

312
The `AtlassianRestAPI` base class provides common functionality for all Atlassian product clients.
313

314
```python { .api }
315
class AtlassianRestAPI:
316
    def __init__(self, url: str, username: str = None, password: str = None,
317
                 timeout: int = 75, api_root: str = "rest/api", 
318
                 api_version: str = "latest", verify_ssl: bool = True,
319
                 session: Optional[requests.Session] = None,
320
                 oauth: Optional[dict] = None, oauth2: Optional[dict] = None,
321
                 cloud: bool = False, token: Optional[str] = None,
322
                 backoff_and_retry: bool = False, **kwargs):
323
        """
324
        Initialize Atlassian REST API client.
325
        
326
        Parameters:
327
        - url: Base URL of Atlassian instance
328
        - username: Username for authentication
329
        - password: Password or API token for authentication
330
        - timeout: Request timeout in seconds
331
        - api_root: API root path (default "rest/api")
332
        - api_version: API version ("latest" or specific version)
333
        - verify_ssl: Verify SSL certificates
334
        - session: Custom requests session
335
        - oauth: OAuth 1.0a configuration dict
336
        - oauth2: OAuth 2.0 configuration dict
337
        - cloud: True for Cloud, False for Server/Data Center
338
        - token: Bearer token for authentication
339
        - backoff_and_retry: Enable automatic retry with backoff
340
        """
341

342
    def get(self, path: str, **kwargs) -> Union[dict, str, bytes]:
343
        """Execute GET request"""
344
        
345
    def post(self, path: str, data: dict = None, **kwargs) -> Union[dict, str]:
346
        """Execute POST request"""
347
        
348
    def put(self, path: str, data: dict = None, **kwargs) -> Union[dict, str]:
349
        """Execute PUT request"""
350
        
351
    def delete(self, path: str, **kwargs) -> Union[dict, str]:
352
        """Execute DELETE request"""
353
```
354

355
### Common Types
356

357
```python { .api }
358
from atlassian.typehints import T_id, T_resp_json
359
from typing import Union, Optional, List, Dict, Any
360

361
# Resource identifier type
362
T_id = Union[str, int]
363

364
# JSON response type  
365
T_resp_json = Union[dict, None]
366

367
# Common parameter types
368
IssueFields = Dict[str, Any]
369
JQLQuery = str
370
ProjectKey = str
371
IssueKey = str
372
```
373

374
## Common Patterns
375

376
### Pagination
377

378
Many methods support pagination for large result sets:
379

380
```python
381
# Get all issues with pagination
382
all_issues = []
383
start_at = 0
384
max_results = 50
385

386
while True:
387
    results = jira.search_issues(
388
        jql="project = PROJ",
389
        start=start_at,
390
        limit=max_results
391
    )
392
    
393
    all_issues.extend(results["issues"])
394
    
395
    if len(results["issues"]) < max_results:
396
        break
397
        
398
    start_at += max_results
399
```
400

401
### Bulk Operations
402

403
```python
404
# Bulk create issues
405
issues_data = [
406
    {"summary": "Task 1", "project": "PROJ", "issuetype": "Task"},
407
    {"summary": "Task 2", "project": "PROJ", "issuetype": "Task"},
408
]
409

410
for issue_data in issues_data:
411
    jira.create_issue(**issue_data)
412
```
413

414
### Error Recovery
415

416
```python
417
from atlassian.errors import ApiError
418
import time
419

420
def retry_api_call(func, *args, max_retries=3, **kwargs):
421
    for attempt in range(max_retries):
422
        try:
423
            return func(*args, **kwargs)
424
        except ApiError as e:
425
            if attempt == max_retries - 1:
426
                raise
427
            time.sleep(2 ** attempt)  # Exponential backoff
428
```