abysshub

The official Python library for the Abyss API.

Pre-release: the Abyss API opens soon.

from abysshub import Abyss, AbyssError

abyss = Abyss()  # reads ABYSS_API_KEY

try:
    run = abyss.run("widget_131", {"amount": 250000})
    print(run.result)
except AbyssError as error:
    print(error.code, error.param, error.request_id, error.run)

run() presses the Widget and waits for the run to end, however long it takes, then returns the succeeded run. A refusal or a failed run raises AbyssError.

It runs on Python 3.10+, with one dependency, httpx.

The client

abyss = Abyss(api_key=None, base_url=None, max_retries=2)

api_key: defaults to ABYSS_API_KEY. Without a key, Abyss() raises AbyssError with code == "invalid_api_key".
base_url: defaults to ABYSS_BASE_URL, else https://api.abysshub.com. A key starting abyss_sk_dev_ goes to https://api.dev.abysshub.com.

abyss.close() closes its connections; with Abyss() as abyss: does it for you.

run = abyss.run(widget, input, max_price=None, idempotency_key=None)

widget is widget_<id>, or an unlisted Widget's private token.
input is the Widget's Fields by name, as a dict.
max_price: the most the run may cost, in Byssium. A higher price is refused with price_above_max, and nothing is charged.
idempotency_key: each call presses with a fresh UUID Idempotency-Key unless you give one.

The press holds until the run ends. When the hold ends early (a deploy cuts it, the API's holds are all taken, or an hour passes), run() re-attaches with GET <Location>?wait=true until the run ends. Re-attaching has no limit and is not a retry. Connecting has 10 s, and 30 s of silence counts as a cut.

A run is a dataclass with /v1's fields: id, widget, status (queued, running, succeeded or failed), price, result (the Widget's JSON, a dict when it wrote an object), output_files, error, created_at, started_at and ended_at.

Errors

A refusal or a failed run raises one AbyssError. Branch on code:

code, message, param, doc_url, request_id: from /v1's error body. A failed run's code is widget_fault, platform_fault or budget_exceeded.
status: the HTTP status of a refusal; None for a failed run.
run: the failed run; None for a refusal.

The library's own codes: invalid_api_key (no key), connection_error (the connection dropped before the API answered) and unexpected_response (an answer that is not /v1's).

Metadata

Release files for abysshub 0.0.1.dev8

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

Source distribution (sdist)

Source distribution for abysshub 0.0.1.dev8
File	Size	Uploaded
abysshub-0.0.1.dev8.tar.gz	10.0 kB	Oct 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for abysshub 0.0.1.dev8
File	Interpreter	ABI	Platform	Reset
abysshub-0.0.1.dev8-py3-none-any.whl 8.3 kB Oct 5, 2026	Python 3	none	any	Details

Total release size: 18.3 kB

Release files / abysshub-0.0.1.dev8.tar.gz

Download URL	abysshub-0.0.1.dev8.tar.gz
Size	10.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`54d2f504e394406c1445c43120e026d66f794601ea23bb7dbbfdd2bea2e6f668`
BLAKE2b-256 checksum How to use checksums	`dcb80dd432b3fdf956a80b7d1c6bf521bf574fa67119b3fa8631c940a831ffe4`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Abysshub/abysshub-sdk
Publishing commit: github.com/Abysshub/abysshub-sdk/tree/125d93c68ad034df131553f7207a5515fd469f29

Workflow

Publishing configuration: github.com/Abysshub/abysshub-sdk/blob/125d93c68ad034df131553f7207a5515fd469f29/.github/workflows/release.yml
Publishing logs: github.com/Abysshub/abysshub-sdk/actions/runs/37309266529/attempts/1

Artifact

Subject: abysshub-0.0.1.dev8.tar.gz
SHA-256 checksum: 54d2f504e394406c1445c43120e026d66f794601ea23bb7dbbfdd2bea2e6f668 Verifying attestations

Release files / abysshub-0.0.1.dev8-py3-none-any.whl

Download URL	abysshub-0.0.1.dev8-py3-none-any.whl
Size	8.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e22a35bc0186c0a40e6794dd6f1680b10b9edbbef9dbc701b39e426e32c10fe0`
BLAKE2b-256 checksum How to use checksums	`55b9b7f77517522f21a7dfee5620beabff1ccfbff62f163532d45de76eb91685`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Abysshub/abysshub-sdk
Publishing commit: github.com/Abysshub/abysshub-sdk/tree/125d93c68ad034df131553f7207a5515fd469f29

Workflow

Publishing configuration: github.com/Abysshub/abysshub-sdk/blob/125d93c68ad034df131553f7207a5515fd469f29/.github/workflows/release.yml
Publishing logs: github.com/Abysshub/abysshub-sdk/actions/runs/37309266529/attempts/1

Artifact

Subject: abysshub-0.0.1.dev8-py3-none-any.whl
SHA-256 checksum: e22a35bc0186c0a40e6794dd6f1680b10b9edbbef9dbc701b39e426e32c10fe0 Verifying attestations