Skip to main content

Python Wrapper for Atlassian REST API

PyPI Documentation Code Coverage PyPI - Python Version Commit Check

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.1

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.1
File Interpreter ABI Platform Actions
atlassian_api_py-1.0.1-py3-none-any.whl Python 3 none any Details for atlassian_api_py-1.0.1-py3-none-any.whl

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

Download URL atlassian_api_py-1.0.1-py3-none-any.whl
Size 24.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
315b0985093fe2bc8192bbf8cfec798cb98b7120bd2a406ee44ab66e9ec3b8ca
BLAKE2b-256 checksum
How to use checksums
6e9157fccc9eb93a0396e4d47c595ea130c8a0adbc17d7b795ba6cea763ba124
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for atlassian-api-py 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page