atlassian-api-py

Overview

atlassian-api-py is a small Python wrapper for Atlassian REST APIs. It provides ready-to-use clients for Jira, Bitbucket, and Confluence so you can automate common Atlassian tasks without rewriting endpoint and session handling code.

The clients are intentionally lightweight:

GET helpers return nested SimpleNamespace objects, so response fields can be accessed with dot notation.
POST, PUT, and DELETE helpers return decoded JSON dictionaries when the API returns JSON, or None for empty responses.
HTTP 4xx and 5xx responses raise APIError with the status code and response body.

Documentation: atlassian-api-py.readthedocs.io

Installation

Python 3.9 or newer is required.

Install from PyPI:

pip install atlassian-api-py

Upgrade an existing installation:

pip install --upgrade atlassian-api-py

Quick Start

Create a client for the Atlassian product you want to automate, then call the method that matches the operation.

from atlassian import Jira

jira = Jira(
    url="https://jira.company.com",
    username="your_username",
    password="your_password",
)

issue = jira.issue("TEST-1")
print(f"{issue.key}: {issue.fields.summary}")

Use a token instead of username/password when your Atlassian instance supports bearer token authentication:

from atlassian import Jira

jira = Jira(url="https://jira.company.com", token="your_token")

Usage

You can authenticate with username/password or a token. Pass only the credential type supported by your Atlassian instance.

Using username and password

from atlassian import Jira

jira = Jira(
    url="https://jira.company.com",
    username="your_username",
    password="your_password",
)

Using a token

from atlassian import Jira

jira = Jira(url="https://jira.company.com", token="your_token")

Loading credentials from a file

For scripts, keep credentials outside your source code. One simple option is a local config.ini file that is excluded from version control.

[jira]
url = https://jira.company.com
username = your_username
password = your_password
# Alternatively
token = your_token

import configparser

from atlassian import Jira

config = configparser.ConfigParser()
config.read('config.ini')
section = config["jira"]

jira = Jira(
    url=section["url"],
    username=section.get("username"),
    password=section.get("password"),
    token=section.get("token"),
)

Common Jira tasks

Read issue fields:

issue = jira.issue("TEST-1")
print(issue.fields.status.name)      # e.g. "Triage"
print(issue.fields.description)      # e.g. "This is a demo Jira ticket"
print(issue.fields.issuetype.name)   # e.g. "Bug"

Update an issue:

jira.update_issue_label("TEST-1", add_labels=["automation"])
jira.add_issue_comment("TEST-1", "Checked by an automation script.")

Create an issue:

jira.create_issue(
    fields={
        "project": {"key": "TEST"},
        "summary": "Created from atlassian-api-py",
        "issuetype": {"name": "Task"},
        "description": "This issue was created through the Jira REST API.",
    }
)

Common Bitbucket tasks

from atlassian import Bitbucket

bitbucket = Bitbucket(
    url="https://bitbucket.company.com",
    username="your_username",
    password="your_password",
)

repos = bitbucket.get_project_repo("PROJECT_KEY")
for repo in repos:
    print(repo.name)

bitbucket.create_pull_request(
    project_key="PROJECT_KEY",
    repo_slug="repo_slug",
    title="Add automation update",
    from_branch="feature/automation",
    to_branch="main",
    reviewers=["reviewer_slug"],
)

Common Confluence tasks

from atlassian import Confluence

confluence = Confluence(
    url="https://confluence.company.com",
    username="your_username",
    password="your_password",
)

page = confluence.get_content_by_id(123456)
print(page.title)

confluence.create_content(
    title="Automation Notes",
    space_key="SPACE",
    body_value="<p>Created from atlassian-api-py.</p>",
)

Response handling

GET responses are parsed into nested SimpleNamespace objects when the response body contains JSON:

issue = jira.issue("TEST-1")
print(issue.fields.status.name)

If a response body is not JSON, the raw response text is returned. Empty responses return None. Mutating methods such as post(), put(), and delete() return a decoded dictionary when JSON is available.

Use APIError to handle unsuccessful HTTP responses:

from atlassian.error import APIError

try:
    jira.issue("MISSING-1")
except APIError as exc:
    print(exc.code)
    print(exc.message)

More Jira, Bitbucket, and Confluence examples are available in the documentation.

License

This project is released under the MIT License.

Metadata

Release files for atlassian-api-py 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for atlassian-api-py 1.0.0
File	Interpreter	ABI	Platform	Reset
atlassian_api_py-1.0.0-py3-none-any.whl 24.0 kB Apr 11, 2026	Python 3	none	any	Details

Release files / atlassian_api_py-1.0.0-py3-none-any.whl

Download URL	atlassian_api_py-1.0.0-py3-none-any.whl
Size	24.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6f8274d9ce636aaadd2f84e25272e44204b3c3695d6eabe13ca176237f243603`
BLAKE2b-256 checksum How to use checksums	`72febd52fd411ea145433ff59ea63f62a3598abac40011a5e4c04b441132f224`
Upload date	Apr 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.3`