Python API reference
Package xberg_io_sdk. Every method below is on the client; the async client mirrors the sync one method for method.
Extraction
Section titled “Extraction”Submit documents and wait for results.
| Method | Description |
|---|---|
extract |
Submit a single document for extraction via POST /v1/extract (multipart). |
extract_batch |
Submit multiple documents in a SINGLE multipart request carrying every file. |
extract_and_wait |
Submit a document and block until extraction completes (raises on failure/timeout). |
Poll, read, page through and cancel extraction jobs.
| Method | Description |
|---|---|
list_jobs |
List jobs via GET /v1/jobs (paginated). Returns the decoded response body. |
get_job |
Fetch a tagged extraction or crawl job record (GET /v1/jobs/{id}). |
get_job_result |
Fetch a job’s stored result envelope (GET /v1/jobs/{id}/result). |
get_job_page |
Fetch a rendered page image (GET /v1/jobs/{id}/pages/{n}, image/png bytes). |
cancel_job |
Cancel an extraction job (DELETE /v1/jobs/{id}, 204 whether pending or already terminal). |
wait_for_job |
Poll GET /v1/jobs/{id} until the job reaches a terminal status or timeout elapses. |
wait_for_jobs |
Wait for multiple jobs sequentially (sync). |
audit |
Fetch audit-log entries via GET /v1/audit. Returns the decoded response body. |
Enterprise-only crawl job event stream.
| Method | Description |
|---|---|
stream_crawl_events |
Stream a crawl job’s events (GET /v1/crawl-jobs/{id}/events). |
Presets
Section titled “Presets”The curated preset registry, served by both tiers.
| Method | Description |
|---|---|
presets |
List the curated, read-only managed presets (GET /v1/presets). |
get_preset |
Fetch one managed preset in full (GET /v1/presets/{id}). |
get_preset_sample |
Fetch a preset’s bundled sample document (GET /v1/presets/{id}/sample/{name}, raw bytes). |
Saved presets
Section titled “Saved presets”Project-scoped presets you create and update.
| Method | Description |
|---|---|
list_saved_presets |
List the project’s saved presets (GET /v1/saved_presets, paginated). |
create_saved_preset |
Create a saved preset (POST /v1/saved_presets). |
get_saved_preset |
Fetch one saved preset in full (GET /v1/saved_presets/{preset_id}). |
update_saved_preset |
Replace a saved preset’s definition (PATCH /v1/saved_presets/{preset_id}). |
delete_saved_preset |
Delete a saved preset (DELETE /v1/saved_presets/{preset_id}, 204). |
Collections, documents and retrieval.
| Method | Description |
|---|---|
list_rag_collections |
List RAG collections (GET /v1/rag/collections). |
create_rag_collection |
Create a RAG collection (POST /v1/rag/collections). |
get_rag_collection |
Fetch a RAG collection (GET /v1/rag/collections/{name}). |
delete_rag_collection |
Delete a RAG collection (DELETE /v1/rag/collections/{name}, 204). |
add_rag_documents |
Add documents to a RAG collection (POST /v1/rag/collections/{name}/documents). |
delete_rag_documents |
Delete documents from a RAG collection by ID or filter (DELETE .../documents). |
reindex_rag_document |
Reindex a RAG document (POST /v1/rag/collections/{name}/documents/{id}/reindex). |
rag_retrieve |
Retrieve chunks from a RAG collection (POST /v1/rag/collections/{name}/retrieve). |
migrate_rag_embeddings |
Kick off an embedding migration (POST /v1/rag/collections/{name}/migrate-embeddings). |
get_rag_migration_job |
Poll an embedding-migration job (GET .../migrate-embeddings/{job_id}). |
get_rag_job |
Fetch a RAG job’s status (GET /v1/rag/jobs/{job_id}). |
get_rag_config |
Pro only: fetch a project’s RAG config (GET /v1/projects/{project_id}/rag-config). |
set_rag_config |
Pro only: update a project’s RAG config (PUT /v1/projects/{project_id}/rag-config). |
Auto-tune
Section titled “Auto-tune”Tuning jobs and their results.
| Method | Description |
|---|---|
submit_auto_tune |
Submit an auto-tune job (POST /v1/auto-tune: a JSON request part plus one file part each). |
list_auto_tune_jobs |
List auto-tune jobs (GET /v1/auto-tune, paginated). |
get_auto_tune_status |
Fetch an auto-tune job’s progress (GET /v1/auto-tune/{id}). |
get_auto_tune_result |
Fetch a finished auto-tune job’s leaderboard and winning profile (GET /v1/auto-tune/{id}/result). |
get_auto_tune_capabilities |
Fetch the tunable knobs and OCR backends this instance offers (GET /v1/auto-tune/capabilities). |
promote_auto_tune_profile |
Promote an auto-tune result to a named tuning profile (POST /v1/auto-tune/{id}/promote). |
delete_auto_tune_job |
Delete an auto-tune job and its artifacts (DELETE /v1/auto-tune/{id}, 204). |
Tuning profiles
Section titled “Tuning profiles”Profiles promoted from auto-tune runs.
| Method | Description |
|---|---|
list_tuning_profiles |
List the promoted tuning profiles (GET /v1/tuning-profiles, paginated). |
get_tuning_profile |
Fetch one tuning profile in full (GET /v1/tuning-profiles/{id}). |
delete_tuning_profile |
Delete a tuning profile (DELETE /v1/tuning-profiles/{id}, 204). |
Documents and lineage
Section titled “Documents and lineage”Enterprise-only document history.
| Method | Description |
|---|---|
get_document |
Enterprise only: fetch a document’s latest version (GET /v1/documents/{document_id}). |
versions |
Enterprise only: list a document’s versions (GET /v1/documents/{id}/versions). |
diff |
Enterprise only: diff document versions (GET /v1/documents/{id}/diff). |
get_diff_job |
Enterprise only: poll a diff job (GET /v1/documents/{id}/diff/{diff_job_id}). |
Enrich
Section titled “Enrich”Enterprise-only text enrichment.
| Method | Description |
|---|---|
submit_enrich |
Submit text for enrichment (POST /v1/enrich, 202 Accepted). |
get_enrich_status |
Poll an enrichment job (GET /v1/enrich/{job_id}). |
Uploads and usage
Section titled “Uploads and usage”Enterprise-only upload staging and metering.
| Method | Description |
|---|---|
presign_upload |
Request presigned upload URLs (POST /v1/uploads/presign). Returns the decoded body. |
confirm_upload |
Confirm a presigned upload batch and enqueue extraction (POST /v1/uploads/confirm, 202). |
usage |
Fetch aggregate extraction usage for a date range (GET /v1/usage). |
list_extraction_events |
Enterprise only: list recent extraction events (GET /v1/extractions). |
Control plane
Section titled “Control plane”Pro-only projects, keys and integrations.
| Method | Description |
|---|---|
list_projects |
Pro only: list the caller’s projects (GET /v1/projects, paginated). |
create_project |
Pro only: create a project (POST /v1/projects). |
list_api_keys |
Pro only: list a project’s API keys (GET /v1/projects/{project_id}/api-keys). |
create_api_key |
Pro only: mint a project API key (POST /v1/projects/{project_id}/api-keys). |
revoke_api_key |
Pro only: revoke an API key (DELETE /v1/projects/{project_id}/api-keys/{key_id}). |
list_integrations |
Pro only: list a project’s integrations (GET /v1/projects/{project_id}/integrations). |
create_integration |
Pro only: create an integration (POST /v1/projects/{project_id}/integrations). |
get_integration |
Pro only: fetch one integration (GET .../integrations/{integration_id}). |
delete_integration |
Pro only: delete an integration (DELETE .../integrations/{integration_id}). |
connect_integration |
Pro only: begin the OAuth connect flow (POST .../integrations/{integration_id}/connect). |
disconnect_integration |
Pro only: drop an integration’s stored credentials (POST .../disconnect). |
list_integration_documents |
Pro only: list documents visible through an integration (GET .../documents). |
fetch_integration_document |
Pro only: download one document through an integration (GET .../documents/{document_id}). |
Enterprise control plane
Section titled “Enterprise control plane”All backend operations use the configured control-plane origin and credential.
| Method | Description |
|---|---|
delete_account |
Enterprise backend: Delete the authenticated user’s account and all associated data (DELETE /auth/account). |
get_auth_config |
Enterprise backend: GET /auth/config: which auth methods this instance accepts. (GET /auth/config). |
get_user_profile |
Enterprise backend: Get the authenticated user’s durable profile (GET /auth/profile). |
update_user_profile |
Enterprise backend: Update the authenticated user’s display name (PATCH /auth/profile). |
backend_login |
Enterprise backend: Authenticate with an OIDC ID token and receive a backend JWT (POST /auth/login). |
healthz |
Enterprise backend: Liveness probe - returns 200 if the process is running (GET /healthz). |
readyz |
Enterprise backend: Readiness probe - returns 200 if the service can handle traffic (GET /readyz). |
accept_invitation |
Enterprise backend: Accept an invitation using a token (POST /v1/invitations/accept). |
oauth_callback |
Enterprise backend: OAuth callback handler (GET /v1/oauth/callback). |
backend_list_projects |
Enterprise backend: List all projects for the authenticated user (GET /v1/projects). |
backend_create_project |
Enterprise backend: Create a new project (POST /v1/projects). |
get_project |
Enterprise backend: Get project details by ID (GET /v1/projects/{id}). |
delete_project |
Enterprise backend: Delete a project (DELETE /v1/projects/{id}). |
update_project |
Enterprise backend: Update project details (PATCH /v1/projects/{id}). |
get_analytics |
Enterprise backend: Get analytics data for a project within a date range (GET /v1/projects/{id}/analytics). |
backend_list_api_keys |
Enterprise backend: List all API keys for a project (GET /v1/projects/{id}/api-keys). |
backend_create_api_key |
Enterprise backend: Create a new API key for a project (POST /v1/projects/{id}/api-keys). |
backend_revoke_api_key |
Enterprise backend: Revoke an API key (DELETE /v1/projects/{id}/api-keys/{key_id}). |
regenerate_api_key |
Enterprise backend: Regenerate an API key (POST /v1/projects/{id}/api-keys/{key_id}/regenerate). |
list_project_audit |
Enterprise backend: List a project’s audit events, most recent first. (GET /v1/projects/{id}/audit). |
get_billing |
Enterprise backend: Get billing and quota information for a project (GET /v1/projects/{id}/billing). |
create_checkout |
Enterprise backend: Create a Stripe Checkout Session for a project (POST /v1/projects/{id}/billing/checkout). |
create_portal |
Enterprise backend: Create a Stripe Customer Portal Session for a project (POST /v1/projects/{id}/billing/portal). |
backend_list_integrations |
Enterprise backend: List all integrations for a project (GET /v1/projects/{id}/integrations). |
backend_create_integration |
Enterprise backend: Create a new integration (POST /v1/projects/{id}/integrations). |
backend_get_integration |
Enterprise backend: Get a specific integration (GET /v1/projects/{id}/integrations/{iid}). |
backend_delete_integration |
Enterprise backend: Delete an integration (DELETE /v1/projects/{id}/integrations/{iid}). |
oauth_connect |
Enterprise backend: Begin an OAuth authorization flow for an integration (owner-gated). (POST /v1/projects/{id}/integrations/{iid}/connect). |
backend_disconnect_integration |
Enterprise backend: Disconnect an integration (revoke OAuth connection) (POST /v1/projects/{id}/integrations/{iid}/disconnect). |
backend_list_integration_documents |
Enterprise backend: List documents in a connected integration (GET /v1/projects/{id}/integrations/{iid}/documents). |
backend_fetch_integration_document |
Enterprise backend: Fetch a single document from a connected integration (GET /v1/projects/{id}/integrations/{iid}/documents/{doc_id}). |
backend_get_integration_sync |
Enterprise backend: Report the durable synchronization state for one source integration (GET /v1/projects/{id}/integrations/{iid}/sync). |
backend_set_integration_sync |
Enterprise backend: Enable or disable durable synchronization for one source integration (PUT /v1/projects/{id}/integrations/{iid}/sync). |
list_invitations |
Enterprise backend: List pending invitations for a project (GET /v1/projects/{id}/invitations). |
invite_user |
Enterprise backend: Create a project invitation (sends token for email delivery by frontend) (POST /v1/projects/{id}/invitations). |
revoke_invitation |
Enterprise backend: Revoke a pending invitation (DELETE /v1/projects/{id}/invitations/{inv_id}). |
leave_project |
Enterprise backend: Self-service: caller leaves a project they belong to (POST /v1/projects/{id}/leave). |
list_members |
Enterprise backend: List all members of a project (GET /v1/projects/{id}/members). |
remove_member |
Enterprise backend: Remove a member from a project (DELETE /v1/projects/{id}/members/{user_id}). |
update_member_role |
Enterprise backend: Update a member’s role in a project (PATCH /v1/projects/{id}/members/{user_id}). |
assign_project_role |
Enterprise backend: Replace the additive custom roles for an existing MEMBER project membership (PATCH /v1/projects/{id}/members/{user_id}/custom-role). |
backend_get_rag_config |
Enterprise backend: Read a project’s RAG configuration. (GET /v1/projects/{id}/rag-config). |
backend_set_rag_config |
Enterprise backend: Set a project’s RAG configuration. (PUT /v1/projects/{id}/rag-config). |
list_project_roles |
Enterprise backend: List the custom authorization roles configured for a project (GET /v1/projects/{id}/roles). |
create_project_role |
Enterprise backend: Create a custom project role with an explicit set of permissions (POST /v1/projects/{id}/roles). |
get_project_role |
Enterprise backend: Retrieve one custom project role and its exact permission set (GET /v1/projects/{id}/roles/{role_id}). |
update_project_role |
Enterprise backend: Replace a custom project role’s name, description, and permissions (PATCH /v1/projects/{id}/roles/{role_id}). |
delete_project_role |
Enterprise backend: Delete a custom project role and clear it from members and invitations (DELETE /v1/projects/{id}/roles/{role_id}). |
list_saml_domains |
Enterprise backend: List project SAML discovery domains and their DNS verification state (GET /v1/projects/{project_id}/saml/domains). |
create_saml_domain |
Enterprise backend: Create a project SAML discovery domain with a DNS TXT verification challenge (POST /v1/projects/{project_id}/saml/domains). |
verify_saml_domain |
Enterprise backend: Check the hosted DNS TXT challenge before enabling domain-based SAML discovery (POST /v1/projects/{project_id}/saml/domains/{domain}/verify). |
list_saml_providers |
Enterprise backend: List the SAML identity providers configured for a project (GET /v1/projects/{project_id}/saml/providers). |
create_saml_provider |
Enterprise backend: Create a project SAML identity provider from uploaded metadata XML (POST /v1/projects/{project_id}/saml/providers). |
update_saml_provider |
Enterprise backend: Replace a project SAML provider configuration and its signing metadata (PUT /v1/projects/{project_id}/saml/providers/{provider_id}). |
delete_saml_provider |
Enterprise backend: Delete a project SAML provider and its dependent domains and identities (DELETE /v1/projects/{project_id}/saml/providers/{provider_id}). |
sandbox_extract |
Enterprise backend: Extract a document in the sandbox (first page only) (POST /v1/projects/{id}/sandbox/extract). |
list_scim_connections |
Enterprise backend: List the project’s SCIM provisioning connections without client secrets (GET /v1/projects/{id}/scim/connections). |
create_scim_connection |
Enterprise backend: Create the project’s SCIM provisioning connection; the client secret is returned once (POST /v1/projects/{id}/scim/connections). |
list_scim_admin_groups |
Enterprise backend: List provisioned SCIM groups and the project roles mapped to each (GET /v1/projects/{id}/scim/connections/{connection_id}/groups). |
replace_scim_group_roles |
Enterprise backend: Replace the complete project-role mapping for one provisioned SCIM group (PUT /v1/projects/{id}/scim/connections/{connection_id}/groups/{group_id}/roles). |
rotate_scim_connection_secret |
Enterprise backend: Rotate a SCIM connection credential and revoke every token issued before it (POST /v1/projects/{id}/scim/connections/{connection_id}/rotate). |
get_usage |
Enterprise backend: Get usage statistics for a project within a date range (GET /v1/projects/{id}/usage). |
list_webhooks |
Enterprise backend: List all webhooks for a project (GET /v1/projects/{id}/webhooks). |
create_webhook |
Enterprise backend: Create a new webhook for a project (POST /v1/projects/{id}/webhooks). |
delete_webhook |
Enterprise backend: Delete a webhook (DELETE /v1/projects/{id}/webhooks/{wh_id}). |
update_webhook |
Enterprise backend: Update a webhook’s configuration (PATCH /v1/projects/{id}/webhooks/{wh_id}). |
list_webhook_deliveries |
Enterprise backend: List delivery attempts recorded for a webhook. (GET /v1/projects/{id}/webhooks/{wh_id}/deliveries). |
retry_webhook_delivery |
Enterprise backend: Manually retry one past delivery attempt. (POST /v1/projects/{id}/webhooks/{wh_id}/deliveries/{delivery_id}/retry). |
test_webhook |
Enterprise backend: Send a test delivery to a webhook endpoint (POST /v1/projects/{id}/webhooks/{wh_id}/test). |
public_sandbox_extract |
Extract in the public sandbox; pass its optional OIDC bearer as sandbox_token. |
Pro health
Section titled “Pro health”Pro liveness and coarse license/capability state.
| Method | Description |
|---|---|
pro_healthz |
Pro liveness and coarse license/capability state (GET /healthz), rather than dependency readiness. |
Pro-only session and configuration reads.
| Method | Description |
|---|---|
auth_config |
Pro only: fetch the instance’s accepted auth methods (unauthenticated GET /auth/config). |
login |
Pro only: exchange a verified OIDC ID token for a Pro session JWT (POST /auth/login). |
| Method | Description |
|---|---|
get_integration_sync |
Pro only: read durable synchronization state for an integration. |
get_license_info |
Pro only: report the instance’s license state and entitlements (GET /v1/license). |
get_subscription_delivery |
Enterprise only: read one delivery’s payload previews (GET /v1/webhooks/{id}/deliveries/{delivery_id}). |
get_webhook_delivery |
Enterprise backend: Fetch bounded payload previews for one retained managed attempt. (GET /v1/projects/{id}/webhooks/{wh_id}/deliveries/{delivery_id}). |
list_managed_embedding_presets |
List the curated embedding presets a RAG collection may name (GET /v1/rag/embedding-presets). |
list_subscription_deliveries |
Enterprise only: list a subscription’s delivery attempts (GET /v1/webhooks/{id}/deliveries). |
put_local_upload |
Pro only: write document bytes against a presigned capability (PUT /v1/uploads/local/{project_id}/{token}, 204). |
set_integration_sync |
Pro only: enable or disable durable synchronization for an integration. |
stop_auto_tune_job |
Stop a running auto-tune job, keeping its artifacts (POST /v1/auto-tune/{id}/stop, 204). |