Atlassian Python API Guide for Automation

The Atlassian Python API is a powerful tool. It lets you control Jira, Confluence, and Bitbucket from your Python scripts. You can automate tasks and manage data. This saves time and reduces errors.

This guide will show you how to start. We will cover setup, basic operations, and real examples. You will learn to interact with Atlassian's ecosystem programmatically.

What is the Atlassian Python API?

The Atlassian Python API refers to libraries that wrap the REST APIs of Atlassian products. The main library is called `atlassian-python-api`. It provides a simple Pythonic interface.

You do not need to craft raw HTTP requests. The library handles authentication, pagination, and data formatting for you. This makes integration much smoother.

It supports Jira Software, Jira Service Management, Confluence, and Bitbucket. You can manage issues, pages, repositories, and more. This is essential for DevOps and project automation.

Setting Up Your Environment

First, you need to install the library. Use pip, the Python package installer. Open your terminal or command prompt.

pip install atlassian-python-api
    

You also need access to an Atlassian instance. This could be Atlassian Cloud or a self-hosted Data Center/server. You will need a username and API token or password.

For Cloud, generate an API token from your Atlassian account security page. For server, you might use your username and password. Always store credentials securely, using environment variables.

If you are new to working with APIs in Python, our Python API Calls Guide for Beginners covers the foundational concepts.

Authenticating and Creating a Client

Authentication is the first step. Import the library and create a client for your tool. Here is an example for Jira Cloud.

# Import the Jira class from the library
from atlassian import Jira

# Define your credentials and instance URL
url = "https://your-domain.atlassian.net"
email = "[email protected]"
api_token = "your-api-token-here"  # Store this securely!

# Create the Jira client object
jira = Jira(
    url=url,
    username=email,
    password=api_token,  # For Cloud, the API token is used as the password
    cloud=True
)

print("Jira client created successfully.")
    

Jira client created successfully.
    

The Jira class constructor takes the site URL and credentials. Setting cloud=True is important for Cloud instances. For Confluence or Bitbucket, you would use the Confluence or Bitbucket classes similarly.

Performing Basic Jira Operations

Let's look at common tasks. We will create, read, and update a Jira issue.

1. Creating a New Issue

Use the create_issue method. You must specify the project key, issue type, summary, and description.

# Define the issue fields
issue_dict = {
    'project': {'key': 'PROJ'},
    'summary': 'Automate issue creation via Python API',
    'description': 'This issue was created automatically using the atlassian-python-api library.',
    'issuetype': {'name': 'Task'},
}

# Create the issue
new_issue = jira.create_issue(fields=issue_dict)

# Print the key of the newly created issue (e.g., PROJ-123)
print(f"Created issue: {new_issue['key']}")
    

Created issue: PROJ-101
    

The method returns a dictionary containing the new issue's data, including its unique key. This is a fundamental skill for Python API Data Pulling Guide workflows where you create tickets from external data.

2. Fetching an Issue

To get details of an issue, use the issue method with the issue key.

# Fetch an existing issue
issue_key = 'PROJ-101'
issue = jira.issue(issue_key)

# Print the summary and status
print(f"Summary: {issue['fields']['summary']}")
print(f"Status: {issue['fields']['status']['name']}")
    

Summary: Automate issue creation via Python API
Status: To Do
    

3. Updating an Issue

You can transition an issue or edit its fields. First, find the transition ID for the desired action (e.g., "In Progress").

# Get available transitions for the issue
transitions = jira.get_issue_transitions(issue_key)
# print(transitions) # Uncomment to see the list

# Let's assume the transition to 'In Progress' has id '21'
transition_id = '21'

# Execute the transition
jira.issue_transition(issue_key, transition_id)
print(f"Issue {issue_key} transitioned to 'In Progress'.")

# Update a field, like priority
update_data = {
    "fields": {
        "priority": {"name": "High"}
    }
}
jira.update_issue_field(issue_key, update_data)
print(f"Issue {issue_key} priority set to High.")
    

Issue PROJ-101 transitioned to 'In Progress'.
Issue PROJ-101 priority set to High.
    

Handling data types like transition IDs correctly is crucial. For more on managing different data formats, see the Python API Number Handling Guide.

Working with Confluence

The process is similar for Confluence. You create a Confluence client. Then you can manage pages and spaces.

from atlassian import Confluence

confluence = Confluence(
    url='https://your-domain.atlassian.net/wiki',
    username='[email protected]',
    password='your-api-token',
    cloud=True
)

# Create a new page in a space
space_key = 'DOC'
page_title = 'My API Documentation'
page_content = '
This page was created via the Python API.
Features
Automation is great.
'

status = confluence.create_page(
    space=space_key,
    title=page_title,
    body=page_content,
    parent_page_id=None,  # Top-level page
    type='page',
    representation='storage'  # Confluence Storage Format
)

if status:
    print(f"Page '{page_title}' created successfully in space {space_key}.")
    

Page 'My API Documentation' created successfully in space DOC.
    

Best Practices and Error Handling

Always use try-except blocks. API calls can fail due to network issues or invalid data.

try:
    issue = jira.issue('PROJ-99999')  # Non-existent