xberg-io-sdk

Official Python client for the Xberg Enterprise and Xberg Pro document-processing APIs — one client, two targets.

• httpx-based, sync (XbergClient) and async (AsyncXbergClient) surfaces
• One client speaks to both products: shared extraction/jobs/presets/auto-tune/RAG surface, plus capability-gated tier-specific methods (Pro auth and control plane; Enterprise uploads/usage/document diff/enrichment)
• Generated from two OpenAPI 3.1 specs (Enterprise + Pro), then wrapped in ergonomic helpers
• Configurable retry engine (honors Retry-After, exponential backoff)
• Type-annotated end to end, py.typed shipped

Install

pip install xberg-io-sdk
# or
uv add xberg-io-sdk

Requires Python 3.10+.

Quickstart

Sync — single file with explicit API key

from pathlib import Path
from xberg_io_sdk import XbergClient

# Enterprise (base_url defaults to https://api.xberg.io)
with XbergClient(api_key="kz_...") as client:
    job = client.extract_and_wait(file=Path("invoice.pdf"))
    if job.result is not None:
        print(job.result.content)

Connecting to Xberg Pro

Pro is self-hosted and has no default URL — pass base_url (and, to skip the /healthz tier probe, target="pro"):

from xberg_io_sdk import XbergClient

with XbergClient(api_key="kz_...", base_url="https://pro.internal", target="pro") as client:
    config = client.auth_config()          # Pro-only
    presets = client.list_saved_presets()  # both tiers; the path spelling follows the tier

Saved presets are served by both products under different spellings — /v1/saved_presets on Enterprise, /v1/saved-presets on Pro. The client renders the right one from the resolved tier, so the same call works against either target.

Async — batch extract with parallel waits

import asyncio
from pathlib import Path
from xberg_io_sdk import AsyncXbergClient

async def main() -> None:
    async with AsyncXbergClient(api_key="kz_...") as client:
        jobs = await client.extract_batch([Path("a.pdf"), Path("b.pdf"), Path("c.pdf")])
        results = await client.wait_for_jobs([str(j.id) for j in jobs])
        for job in results:
            print(job.filename, job.status)

asyncio.run(main())

Public API

One XbergClient (sync) / AsyncXbergClient (async) serves both products. Constructor: (api_key=None, base_url=None, target=None, timeout=30, headers=None, retries=0, retry_on=..., retry_backoff="exponential").

Shared methods (both tiers):

Tier-specific methods are capability-gated — calling one against the wrong tier raises a clear error instead of a raw 404:

• Pro only: login, auth_config, get_rag_config/set_rag_config
• Pro only (control plane): list_projects/create_project, list_api_keys/create_api_key/revoke_api_key, list_integrations/create_integration/get_integration/delete_integration, connect_integration/disconnect_integration, list_integration_documents/fetch_integration_document
• Enterprise only: versions, get_document, diff/get_diff_job, presign_upload/confirm_upload, usage, list_extraction_events, get_job_page (raw image/png bytes), submit_enrich/get_enrich_status, stream_crawl_events (a generator of Server-Sent Events)

Deliberately not exposed

Three documented routes have no client method, on purpose:

• GET /readyz — an infrastructure readiness probe for orchestrators, not caller-facing API surface. GET /healthz is exposed indirectly: it is the tier probe behind target=None.
• GET /v1/oauth/callback (Pro) — a browser redirect leg of the OIDC flow. The provider calls it, not an API client.
• DELETE /auth/account (Pro) — a session-cookie account-deletion flow, not API-key surface. POST /auth/login is exposed because it mints the session JWT this client can then send as a bearer token.

Errors are raised as one of: XbergError (base), AuthError (401 and 403), ValidationError, NotFoundError, RateLimitError (carries retry_after), ServerError, TimeoutError.

Documentation

• SDK docs: https://docs.sdks.xberg.io
• Full reference and guides: https://enterprise.xberg.io

License

MIT — © Kreuzberg, Inc.