The atlassian-python-api library provides a simple and convenient way to interact with Atlassian products (such as Jira Service management, Jira Software, Confluence, Bitbucket and apps Insight, X-Ray) using Python. It is based on the official REST APIs of these products, as well as additional private methods and protocols (such as xml+rpc and raw HTTP requests). This library can be used to automate tasks, integrate with other tools and systems, and build custom applications that interact with Atlassian products. It supports a wide range of Atlassian products, including Jira, Confluence, Bitbucket, StatusPage and others, and is compatible with both Atlassian Server and Cloud instances.
Overall, the atlassian-python-api is a useful tool for Python developers who want to work with Atlassian products. It is well-documented and actively maintained, and provides a convenient way to access the full range of functionality offered by the Atlassian REST APIs and made with love for Atlassian.
From PyPI
$ pip install atlassian-python-apiFrom Source
- Git clone repository
- Use
pip install -r requirements.txtto install the required packages - or
pipenv install && pipenv install --dev
More examples in examples/ directory.
Here's a short example of how to create a Confluence page:
from atlassian import Confluence
import requests
# If you want to use a session, you can create it like this:
session = requests.Session()
# and pass it to the Confluence constructor
confluence = Confluence(
url='http://localhost:8090',
username='admin',
password='admin',
session=session,)
status = confluence.create_page(
space='DEMO',
title='This is the title',
body='This is the body. You can use <strong>HTML tags</strong>!')
print(status)Use token= for a Jira or Confluence Server/Data Center personal access
token. It is sent as a Bearer token:
from atlassian import Confluence, Jira
confluence = Confluence("https://confluence.company.example", token="server-or-dc-pat")
jira = Jira("https://jira.company.example", token="server-or-dc-pat")Atlassian Cloud API tokens use HTTP Basic authentication: pass the account
email as username and the API token as password. Do not pass a Cloud
API token to token=. The latter creates a Bearer header and Cloud commonly
responds with 403 Failed to parse Connect Session Auth Token. requests
encodes the required email:api_token Basic credentials automatically; do
not base64-encode them yourself.
from atlassian import Confluence, Jira
confluence = Confluence(
"https://your-domain.atlassian.net",
username="you@example.com",
password="cloud-api-token",
cloud=True,
timeout=120, # Optional; useful on slow/VPN connections.
)
spaces = confluence.get_all_spaces()
jira = Jira(
"https://your-domain.atlassian.net",
username="you@example.com",
password="cloud-api-token",
cloud=True,
timeout=120,
)
epic = jira.enhanced_jql('project = DEMO AND issuetype = Epic', limit=50)
# Confluence Cloud V2 page read. Use the site URL without a trailing /wiki;
# the client adds the required API context.
from atlassian import ConfluenceV2
confluence_v2 = ConfluenceV2(
"https://your-domain.atlassian.net",
username="you@example.com",
password="cloud-api-token",
)
page = confluence_v2.get_page_by_id("123456789", body_format="storage")
storage_xhtml = page["body"]["storage"]["value"]
# Alternative Confluence Cloud V2 page read. Use the site URL without a trailing /wiki;
# the client adds the required API context.
from atlassian import Confluence
confluence_v2 = Confluence(
"https://your-domain.atlassian.net",
username="you@example.com",
password="cloud-api-token",
api_version=2, # Specify API version 2
cloud=True
)
page = confluence_v2.get_page_by_id("123456789", body_format="storage")
storage_xhtml = page["body"]["storage"]["value"]See the detailed authentication documentation for Cloud gateway/scoped-token notes and other authentication methods.
And here's another example of how to get issues from Jira using JQL Query:
from atlassian import Jira
import requests
session = requests.Session()
jira = Jira(
url='http://localhost:8080',
username='admin',
password='admin',
session=session) # Optional: use a session for persistent connections
JQL = 'project = DEMO AND status IN ("To Do", "In Progress") ORDER BY issuekey'
data = jira.jql(JQL)
print(data)The traditional jql method is deprecated for Jira Cloud users, as Atlassian has transitioned to a nextPageToken-based pagination approach instead of startAt. Use enhanced_jql for improved performance and future compatibility.
from atlassian import Jira
import requests
session = requests.Session()
jira = Jira(
url='https://your-jira-instance.atlassian.net',
username='your-email@example.com',
password='your-api-token',
cloud=True, # Ensure this is set to True for Jira Cloud
session=session # Optional: use a session for persistent connections
)
JQL = 'project = DEMO AND status IN ("To Do", "In Progress") ORDER BY issuekey'
# Fetch issues using the new enhanced_jql method
data = jira.enhanced_jql(JQL)
print(data)The library now supports Confluence's v2 API for Cloud instances. The v2 API provides improved performance, new content types, and more consistent endpoint patterns.
from atlassian import ConfluenceV2
# ConfluenceV2 is an explicit Cloud V2 client; no cloud=True flag is needed.
confluence = ConfluenceV2(
url='https://your-instance.atlassian.net',
username='your-email@example.com',
password='your-api-token',
)
# Get pages from a space
pages = confluence.get_pages(space_key='DEMO', limit=10)
# Create a new page
new_page = confluence.create_page(
space_id='DEMO',
title='New Page with v2 API',
body='<p>This page was created using the v2 API</p>'
)
# Use v2-only features like whiteboards
whiteboard = confluence.create_whiteboard(
space_id='DEMO',
title='My Whiteboard',
content='{"version":1,"type":"doc","content":[]}'
)The library includes a compatibility layer to ease migration from v1 to v2 API. See the migration guide in the documentation for details.
Also, you can use the Bitbucket module e.g. for getting project list
from atlassian import Bitbucket
import requests
session= requests.Session()
bitbucket = Bitbucket(
url='http://localhost:7990',
username='admin',
password='admin',
session=session)
data = bitbucket.project_list()
print(data)Now you can use the Jira Service Desk module. See docs. Example to get your requests:
from atlassian import ServiceDesk
import requests
sd = ServiceDesk(
url='http://localhost:7990',
username='admin',
password='admin',
session=requests.Session())
data = sd.get_my_customer_requests()
print(data)Using Insight (CMDB Tool for Jira):
from atlassian import Insight
import requests
session = requests.Session()
insight = Insight(
url='http://localhost:7990',
username='admin',
password='admin',
session=session)
data = insight.get_object(88)
print(data)Using Xray (Test Management tool for Jira):
from atlassian import Xray
import requests
session = requests.Session()
xr = Xray(
url='http://localhost:7990',
username='admin',
password='admin',
session=session)
data = xr.get_tests('TEST-001')
print(data)Using Bamboo:
from atlassian import Bamboo
import requests
session = requests.Session()
bamboo = Bamboo(
url='http://localhost:6990/bamboo/',
token="<TOKEN>",
session=session)
data = bamboo.get_elastic_configurations()
print(data)If you want to see the response in pretty print format JSON. Feel free for use construction like:
from pprint import pprint
# you code here
# and then print using pprint(result) instead of print(result)
pprint(response)First of all, I am happy for any PR requests. Let's fork and provide your changes :) See the Contribution Guidelines for this project for details on how to make changes to this library.
In addition to all the contributors we would like to thank these vendors:
- Atlassian for developing such a powerful ecosystem.
- JetBrains for providing us with free licenses of PyCharm
- Microsoft for providing us with free licenses of VSCode
- Cursor.com for AI assistance in development
- John B Batzel (batzel@upenn.edu) for implementing the Confluence Cloud v2 API support