Skip to main content

Xberg

xberg-io-sdk

Xberg Enterprise

PyPI npm Go Reference License Documentation CI

Discord

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.11+.

Quickstart

Sync — single file with explicit API key

from pathlib import Path
from xberg_io_sdk import XbergClient

# Enterprise and Pro are self-hosted; pass your deployment URL.
with XbergClient(api_key="kz_...", base_url="https://xberg.example.com") 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

Both products have 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 at /v1/saved_presets, 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_...", base_url="https://xberg.example.com") 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", retry_non_idempotent=False). With retries set, 429 is retried for every method and 502/503/504 only for GET/HEAD/OPTIONS/PUT/DELETE without If-Match; retry_non_idempotent=True extends those statuses to POST/PATCH and to If-Match writes, whose replay fails with 412 once the first attempt applied. A replayed DELETE whose first attempt applied raises NotFoundError. base_url must name the deployment; omitting it raises XbergError.

Shared methods (both tiers):

Method Purpose
extract(file=..., options=..., webhook=...) Submit one document, get back a Job.
extract_batch(files, options=...) Submit many documents in ONE multipart request.
get_job(job_id) Fetch a tagged extraction or crawl record.
wait_for_job(job_id, timeout=300, ...) Poll until terminal (raises on failed/cancelled).
wait_for_jobs(job_ids, ...) Wait for multiple jobs.
extract_and_wait(file=..., ...) Submit + wait in one call.
get_job_result(job_id) Fetch a job's stored JobResult envelope.
list_jobs(...), audit(...) List jobs / read the audit log.
cancel_job(job_id) Cancel a job (idempotent — also 204s if already terminal).
list_rag_collections(), rag_retrieve(name, body), get_rag_job(job_id), … RAG collections/documents/retrieval.
delete_rag_documents(name, body) Delete documents from a collection by ID list or metadata filter.
presets(), get_preset(id), get_preset_sample(id, name) Curated managed presets.
usage(...) Per-project usage totals for a date window.
presign_upload(body), confirm_upload(body) Stage a large document in object storage, then submit it; return PresignUploadResponse / ConfirmUploadResponse.
get_job_page(job_id, page_number) A rendered page image, as raw image/png bytes.
submit_enrich(body), get_enrich_status(job_id) Keyword, entity and label enrichment over extracted text.
stream_crawl_events(crawl_job_id) A generator of Server-Sent Events for a running crawl.
stop_auto_tune_job(id) Stop a running auto-tune job.
list_managed_embedding_presets() The deployment's available embedding presets.
list_saved_presets(...), create_saved_preset(body), get_saved_preset(id), update_saved_preset(id, body), delete_saved_preset(id) Project-owned saved presets.
list_auto_tune_jobs(...), submit_auto_tune(request, files), get_auto_tune_status(id), get_auto_tune_result(id), delete_auto_tune_job(id) Auto-tune runs (submit_auto_tune is multipart).
get_auto_tune_capabilities(), promote_auto_tune_profile(id, body) Discover tunable knobs; promote a run to a named profile.
list_tuning_profiles(...), get_tuning_profile(id), delete_tuning_profile(id) Promoted tuning profiles.

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, get_license_info, put_local_upload
  • 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: enterprise_healthz (returns EnterpriseHealth: tier, rag, auto_tune, data_rooms, decoded leniently), versions, get_document, diff/get_diff_job, list_extraction_events, list_subscription_deliveries/get_subscription_delivery
  • Enterprise only (data rooms): list_documents; list_rooms/create_room/get_room/update_room/delete_room/restore_room; list_room_items/add_room_item/reorder_room_items/remove_room_item/get_room_item_content/download_room_item/get_room_item_page; list_room_members/add_room_member/change_room_member_role/remove_room_member/transfer_room_ownership/leave_room; list_room_invitations/create_room_invitation/revoke_room_invitation/preview_room_invitation/accept_room_invitation; get_room_publication/set_room_publication; and the credential-free get_public_room/list_public_room_items/get_public_room_item_content/download_public_room_item. See the data rooms guide.

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 the tier probe behind target=None, and enterprise_healthz returns it on Enterprise.
  • 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, DataRoomsDisabledError (404 data_room.disabled, a NotFoundError), RequestTimeoutError (408), ResultExpiredError (410), PreconditionFailedError (412), PreconditionRequiredError (428), RateLimitError (carries retry_after), ServerError, GatewayTimeoutError (504, a ServerError), TimeoutError. Every HTTP error carries the server's message, plus status, code and details when sent; the two timeout errors also expose limit and timeout_seconds.

verify_webhook_signature(secret, header, body) checks a delivery's X-Webhook-Signature header (see the webhooks guide).

Documentation

License

MIT — © Kreuzberg, Inc.

Metadata

Release files for xberg-io-sdk 0.11.0

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

Source distribution (sdist)

Source distribution for xberg-io-sdk 0.11.0
File Size Uploaded Provenance Actions
xberg_io_sdk-0.11.0.tar.gz 794.3 kB With provenance Details for xberg_io_sdk-0.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xberg-io-sdk 0.11.0
File Interpreter ABI Platform Actions
xberg_io_sdk-0.11.0-py3-none-any.whl Python 3 none any Details for xberg_io_sdk-0.11.0-py3-none-any.whl

Total release size: 2.9 MB

Release files / xberg_io_sdk-0.11.0.tar.gz

Download URL xberg_io_sdk-0.11.0.tar.gz
Size 794.3 kB
Tags Source
SHA-256 checksum
How to use checksums
09eb51241b828729597c5f23b848ea4044db8b34907b8dd94bb774ad218ac276
BLAKE2b-256 checksum
How to use checksums
14ed94a334fd01c555b8e558e26980bde9bf95fa6777b9d453d5dc79cffacb6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / xberg_io_sdk-0.11.0-py3-none-any.whl

Download URL xberg_io_sdk-0.11.0-py3-none-any.whl
Size 2.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
27903fd00b43a7d59a3bbb1972127b7581d71ae85381a7a9d9e27dc2fd8ebe30
BLAKE2b-256 checksum
How to use checksums
7daf1019252ed0104fc89bd1570cc049dbb3e3533459a001214b800e8bee5c15
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for xberg-io-sdk 0.11.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xberg_io_sdk-0.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

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.

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