Skip to content

Quickstart

Extraction is asynchronous. POST /v1/extract returns 202 with a job ID, a worker extracts the document, and you read the text from the job’s result endpoint once the job finishes. Instead of polling, you can let Xberg call you with a webhook.

You need:

  • A running instance: Docker, Pro on Helm or Enterprise. Both products serve the same extraction routes, so moving between them changes the base URL and key, not the code.
  • The base URL of the instance, for example http://localhost:8080 for a local Docker install.
  • A project API key. The install guides end with creating one.
  • curl and jq for the curl flow, and a PDF named invoice.pdf in the working directory.
  1. Set the base URL and key:

    Terminal window
    export XBERG_URL=http://localhost:8080
    export XBERG_API_KEY=REPLACE_WITH_PROJECT_API_KEY
  2. Submit the file. The response is 202 with { "job_ids": ["<uuid>"], "status": "pending" }:

    Terminal window
    JOB=$(curl -sX POST "$XBERG_URL/v1/extract" \
    -H "Authorization: Bearer $XBERG_API_KEY" \
    -F "file=@invoice.pdf" | jq -r '.job_ids[0]')
    echo "$JOB"
  3. Poll the job until it reaches a terminal status:

    Terminal window
    while true; do
    STATUS=$(curl -s "$XBERG_URL/v1/jobs/$JOB" \
    -H "Authorization: Bearer $XBERG_API_KEY" | jq -r .status)
    case "$STATUS" in completed|partial_success|failed|cancelled) break ;; esac
    sleep 1
    done
    echo "$STATUS"
  4. Read the result. GET /v1/jobs/{id}/result returns the extracted documents once the job is completed or partial_success, and 409 before that:

    Terminal window
    curl -s "$XBERG_URL/v1/jobs/$JOB/result" \
    -H "Authorization: Bearer $XBERG_API_KEY" | jq -r '.results[0].content'

The last command prints the extracted text of the document. If the status was failed, the result endpoint answers 409. Read the reason from GET /v1/jobs/$JOB, whose error field carries it.

The SDKs submit the file, poll with back-off and raise an error when the job fails or is cancelled. extract_and_wait returns the job record, which holds status and statistics but not the extracted text. Fetch the text with get_job_result (getJobResult in TypeScript, GetJobResult in Go).

Python
import asyncio
import os
from pathlib import Path
from xberg_io_sdk import AsyncXbergClient
async def main() -> None:
async with AsyncXbergClient(
base_url=os.environ["XBERG_URL"],
api_key=os.environ["XBERG_API_KEY"],
) as client:
job = await client.extract_and_wait(file=Path("invoice.pdf"))
result = await client.get_job_result(str(job.id))
print(result.results[0].content)
asyncio.run(main())

The Python SDK also offers a blocking XbergClient with the same method names. Install and configure the clients in SDKs.

A single request accepts up to 10 documents inline. Repeat the file part to submit several files in one call (curl: -F "file=@a.pdf" -F "file=@b.pdf"). The response lists one job ID per file under job_ids. For larger batches, use presigned uploads (POST /v1/uploads/presign, then POST /v1/uploads/confirm), which stage up to 100 documents.

GET /v1/jobs/{id} returns one of these status values for an extraction job. Treat completed, partial_success, failed and cancelled as terminal. Any other status means poll again.

status Meaning
pending Queued, not yet picked up
processing A worker is extracting
completed Done. The full result is available at /v1/jobs/{id}/result
partial_success Some pages or files failed. A partial result is available at the same URL
failed Unrecoverable error. The job’s error field carries the reason
cancelled The project cancelled the job

Enterprise adds awaiting_upload, for a job whose document upload is not yet finalized. A crawl job, which GET /v1/jobs/{id} also returns, adds crawling and extracting between pending and the terminal statuses. See Crawling.

The SDKs poll once per second, double the interval after each poll up to 30 seconds, and give up after five minutes. Tune this with poll_interval and timeout in Python (seconds), pollIntervalMs and timeoutMs in TypeScript, and the Wait field of ExtractAndWaitOptions in Go (WaitOptions{Timeout, PollInterval, Backoff}). Do not poll faster than once per second, because rate limits apply.

Status Meaning
401 The key is missing, wrong or expired
403 The key has the read scope and cannot submit work
409 GET /v1/jobs/{id}/result on a job that has not completed successfully
410 The stored result has expired
413 A document exceeds the upload limit
429 The rate limit or, on Pro, the project’s monthly job or page quota is exhausted. Retry-After gives the seconds to wait