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:8080for a local Docker install. - A project API key. The install guides end with creating one.
curlandjqfor the curl flow, and a PDF namedinvoice.pdfin the working directory.
Extract one file
Section titled “Extract one file”-
Set the base URL and key:
Terminal window export XBERG_URL=http://localhost:8080export XBERG_API_KEY=REPLACE_WITH_PROJECT_API_KEY -
Submit the file. The response is
202with{ "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" -
Poll the job until it reaches a terminal status:
Terminal window while true; doSTATUS=$(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 ;; esacsleep 1doneecho "$STATUS" -
Read the result.
GET /v1/jobs/{id}/resultreturns the extracted documents once the job iscompletedorpartial_success, and409before 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.
Use an SDK
Section titled “Use an SDK”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).
import asyncioimport osfrom pathlib import Pathfrom 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())import { XbergClient } from "@xberg-io/sdk";import { readFile } from "node:fs/promises";
const client = new XbergClient({ baseUrl: process.env.XBERG_URL!, apiKey: process.env.XBERG_API_KEY!,});const data = await readFile("invoice.pdf");const job = await client.extractAndWait({ file: { name: "invoice.pdf", data, mimeType: "application/pdf" },});const result = await client.getJobResult(job.id);console.log(result.results?.[0]?.content);package main
import ( "context" "fmt" "log" "os"
xberg "github.com/xberg-io/sdks/packages/go")
func main() { ctx := context.Background() client, err := xberg.New( xberg.WithBaseURL(os.Getenv("XBERG_URL")), xberg.WithAPIKey(os.Getenv("XBERG_API_KEY")), ) if err != nil { log.Fatal(err) } file, err := os.Open("invoice.pdf") if err != nil { log.Fatal(err) } defer file.Close() job, err := client.ExtractAndWait( ctx, xberg.FileSource{Name: "invoice.pdf", Reader: file}, nil, ) if err != nil { log.Fatal(err) } result, err := client.GetJobResult(ctx, job.Id.String()) if err != nil { log.Fatal(err) } if result.Results != nil && len(*result.Results) > 0 { fmt.Println((*result.Results)[0].Content) }}The Python SDK also offers a blocking XbergClient with the same method names. Install and configure the clients in SDKs.
Submit several files
Section titled “Submit several files”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.
Job statuses
Section titled “Job statuses”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.
Errors
Section titled “Errors”| 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 |
Where to next
Section titled “Where to next”- Stop polling and use webhooks.
- Choose output and OCR settings with presets.
- Ingest into a searchable collection with RAG.
- Pull documents from storage and drives with source connectors.
- Install and configure the clients in SDKs. The full client API is at docs.sdks.xberg.io.