Client library

libreserv-client is the official Python client. Python ≥ 3.9, one dependency (httpx), MIT license.

pip install libreserv-client

Synchronous

from libreserv_client import LibreservClient

with LibreservClient("https://convert.example.com", api_key="lsv_...") as client:
    # one call: upload, convert, download
    client.convert("report.docx", "pdf", output="report.pdf")

    # or keep the result in memory
    pdf_bytes = client.convert("report.docx", "pdf")

Asynchronous

AsyncLibreservClient mirrors the sync client method for method:

from libreserv_client import AsyncLibreservClient

async with AsyncLibreservClient(url, api_key=key) as client:
    pdf = await client.convert("report.docx", "pdf")

The job workflow

job = client.submit_job(
    "big-presentation.pptx", "pdf",
    webhook_url="https://myapp.example.com/hooks/libreserv",  # optional
)

job = client.wait_for_job(job.id)      # or rely on the webhook
if job.succeeded:
    client.download_result(job.id, output="deck.pdf")
else:
    print(job.error_code, job.error_msg)

client.job_log(job.id)                 # the server-side conversion log
client.download_source(job.id)         # the original upload
client.list_jobs(status="failed")     # your app's history

Documents can be a path, raw bytes, an open binary file, or a ("filename.docx", payload) pair — the filename drives format detection and the result's download name.

Verifying webhooks

from libreserv_client import parse_webhook, SignatureVerificationError

def hook(request):
    try:
        event = parse_webhook(
            request.body,                          # raw bytes!
            secret=WEBHOOK_SECRET,                 # client.me().webhook_secret
            signature_header=request.headers["X-Libreserv-Signature"],
        )
    except SignatureVerificationError:
        return 403
    if event.succeeded:
        queue_download(event.job_id)
    return 200

Error handling

Everything the library raises derives from LibreservError — network failures included — so one except is exhaustive:

AuthenticationError401 — bad or revoked key, deactivated app
PermissionDeniedError403 — admin endpoint, or source/Referer restrictions
NotFoundError / GoneError404 / 410 — unknown job, or artifacts expired
FileTooLargeError413 — upload over the app's size limit
InvalidRequestError422 — unsupported format, bad fields
ConversionFailedErrorthe document itself cannot be converted; .error_code says why
QuotaExceededError429 — daily / per-minute / concurrency quota
ServiceUnavailableError / ServerError503/507 / any 5xx
TransportErrornetwork failure — DNS, connection, TLS, timeout
WaitTimeoutclient-side wait expired; the job keeps running server-side

Identify your application

client = LibreservClient(url, api_key=key, app_identifier="invoice-service/2.3")

The server records each key's User-Agent, so operators can tell your app's traffic apart when diagnosing issues.