Skip to content
Getting StartedReference

Pythus API Client

Pythus is a Python client for interacting with the Pithus API.

It provides two ways to interact with a Pithus instance:

  • Command-line interface (CLI): Execute API operations directly from a terminal.
  • Python library: Integrate Pithus API operations into your own Python scripts and applications.

The client supports operations such as searching for applications, retrieving analysis reports, checking report status, and uploading or downloading APK files.

The source code is available in the Pithus/pythus GitHub repository.

Before using Pythus, you need:

  • Access to a running Pithus instance with authentication enabled
  • A valid Pithus API key
  • Python 3.14 or later

Pythus uses API key authentication to communicate with your instance.

To retrieve your API key:

  • Log in to your Pithus instance
  • Navigate to the Workspace section
  • On the left side menu, click on the API key

Keep your API key confidential. Anyone with access to it may be able to perform API operations using your account’s permissions.

Clone the Pythus repository:

Terminal window
git clone https://github.com/Pithus/pythus.git
cd pythus

Build the Python package using Poetry:

Terminal window
poetry build

Install the generated wheel:

Terminal window
pip install dist/pythus-0.1.0-py3-none-any.whl

Note: The version in the installation command should match the version of the generated wheel in your dist/ directory.

The package exposes the pythus command-line executable and the pythus Python module.

Pythus needs three main connection parameters:

Parameter Description Default
host Hostname or IP address of the Pithus instance Not configured
port API port 80
api_key API authentication key Not configured
use_https Whether to use HTTPS True
api_prefix API URL prefix /api/

You can provide these settings through command-line arguments, a configuration file, environment variables or directly when initializing the Python client.

Pythus supports TOML configuration files.

Start by copying the example configuration:

Terminal window
cp config_example.toml config.toml

Edit config.toml:

# Pithus instance hostname
host = "pithus.example.org"
# API port
port = 443
# API authentication key
api_key = "YOUR_API_KEY"
# Use HTTPS
use_https = true

Replace the hostname and API key with the values corresponding to your instance.

The configuration file is automatically searched for in the following locations:

  1. ./config.toml – Current working directory.
  2. $XDG_CONFIG_HOME/pythus/config.toml – User configuration directory (defaults to ~/.config/pythus/config.toml).
  3. /etc/pythus/config.toml – System-wide configuration.

Only the first existing configuration file is loaded.

You can also specify a configuration file explicitly using the --config option:

Terminal window
pythus --config /path/to/config.toml list-reports

Pythus also supports environment variables with the PYTHUS_ prefix.

For example:

Terminal window
export PYTHUS_HOST="pithus.example.org"
export PYTHUS_PORT=443
export PYTHUS_API_KEY="YOUR_API_KEY"
export PYTHUS_USE_HTTPS=true

The configuration can then be used without specifying connection parameters on every invocation.

Once installed and configured, the CLI can be accessed through the pythus command.

To display the available commands and options:

Terminal window
$ pythus --help
Usage: pythus [OPTIONS] COMMAND [ARGS]...
Options:
-h, --host TEXT API Host address
-p, --port INTEGER API port [default: 80]
-k, --api-key TEXT Your API key, can be found in the My Hunting tab of
your instance
--https / --no-https Use HTTP instead of HTTPS [default: https]
-b, --beautify Output pretty JSON
-c, --color Output pretty JSON
-f, --config TEXT Path to configuration file.
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or
customize the installation.
--help Show this message and exit.
Commands:
list-reports
get-report
report-status
report-exists
list-apk
upload-apk
download-apk
search

The CLI provides the following commands:

Command Description
list-reports List available analysis reports.
get-report Retrieve an analysis report.
report-status Retrieve the processing status of a report.
report-exists Check whether a report exists.
list-apk List available APK samples.
upload-apk Upload an APK file to Pithus.
download-apk Download an APK sample.
search Search for applications using the Pithus search syntax.

Each command provides its own help:

Terminal window
$ pythus get-report --help
Usage: pythus get-report [OPTIONS] REPORT_ID
Arguments:
REPORT_ID Report identifier (sha256 of the APK) [required]
Options:
--help Show this message and exit.

Retrieve the list of available analysis reports:

Terminal window
pythus list-reports

The response is returned as JSON.

To make the output easier to read:

Terminal window
pythus --beautify list-reports

Reports are identified by the SHA-256 hash of the APK.

Retrieve a report with:

Terminal window
pythus get-report SHA256_HASH

To retrieve the processing status of a report:

Terminal window
pythus report-status SHA256_HASH

To check whether a report exists in Pithus:

Terminal window
pythus report-exists SHA256_HASH

To retrieve the list of available APK samples:

Terminal window
pythus list-apk

To upload an APK file to your Pithus instance:

Terminal window
pythus upload-apk /path/to/application.apk

To download an existing APK using its SHA-256 hash:

Terminal window
pythus download-apk SHA256_HASH

By default, the downloaded file is saved in the current working directory using the following filename:

pithus_sample_SHA256_HASH.apk

You can also specify a custom output path:

Terminal window
pythus download-apk SHA256_HASH ./application.apk

Pythus supports the same search syntax as the search bar on the Pithus homepage.

For example:

Terminal window
pythus search "package_name:com.example.application"

Refer to the Search documentation for more information about search syntax.

Pythus can also be imported into Python scripts and applications.

from pythus.api_client import ApiClient
client = ApiClient(
host="pithus.example.org",
port=443,
api_key="YOUR_API_KEY",
use_https=True,
)

Alternatively, you can initialize the client using a configuration file or environment variables:

from pythus.api_client import ApiClient
from pythus.config import Settings
settings = Settings.load_settings()
client = ApiClient(settings=settings)

Retrieve all available reports:

reports = client.list_reports()

The response is returned as a Python dictionary.

You can access individual reports from the response:

reports = client.list_reports()
for report in reports.get("reports", []):
print(report["apk_hash"])

Retrieve an analysis report using its SHA-256 hash:

report = client.get_report(
"SHA256_HASH"
)

Checking report status

status = client.get_report_status(
"SHA256_HASH"
)

Checking whether a report exists

exists = client.get_report_exists(
"SHA256_HASH"
)

Retrieve the available APK samples:

apk_list = client.list_apk()

Upload an APK file by providing its local filesystem path:

response = client.upload_apk(
"/path/to/application.apk"
)

Download an APK using its SHA-256 hash:

apk = client.download_apk(
"SHA256_HASH"
)
with open("application.apk", "wb") as f:
f.write(apk)

Use the search() method to perform a search using the same query syntax as the Pithus web interface:

results = client.search(
"package_name:com.example.application"
)