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
```