Versioning Documents

Versioning documents

Every extraction is stored against a stable document_id that persists across re-processing. Use these endpoints when an application extracts the same logical document more than once and needs the latest result, the full version history, or a diff between two versions.

All four endpoints are GET and require a Bearer token.

Endpoints

document_id is the UUID returned alongside each extraction job. The from and to query params accept either a version sequence integer or a job UUID.

Get the latest version

curl -s https://api.kreuzberg.dev/v1/documents/$DOC_ID \
  -H "Authorization: Bearer $KREUZBERG_API_KEY"

Returns the latest version's extraction result (same result shape as GET /v1/jobs/{id} — content, tables, images, metadata).

List versions

curl -s https://api.kreuzberg.dev/v1/documents/$DOC_ID/versions \
  -H "Authorization: Bearer $KREUZBERG_API_KEY"

Returns an array of DocumentVersionEntry (paginated). Each entry carries its version sequence number and the job ID that produced it — use either as a from/to value when diffing.

Diff two versions

curl -s "https://api.kreuzberg.dev/v1/documents/$DOC_ID/diff?from=1&to=3" \
  -H "Authorization: Bearer $KREUZBERG_API_KEY"

The diff is computed synchronously and returned inline as 200 when it fits the request budget:

{
  "document_id": "…",
  "from_job_id": "…", "from_version": 1,
  "to_job_id": "…",   "to_version": 3,
  "diff": { "…": "kreuzberg ExtractionDiff shape" },
  "computed_at": "2026-06-20T10:00:00Z"
}

The diff field is the full kreuzberg::diff::ExtractionDiff. The OpenAPI schema declares it opaque because the Rust type recurses; decode it against kreuzberg's published diff schema if you need a typed surface — do not hard-code a shape from this skill.

Async fallback

When the diff exceeds the inline compute budget, the endpoint returns 202 with a job handle instead:

{ "diff_job_id": "…", "status": "pending" }

Poll it the same way you poll extraction jobs — exponential backoff capped at ~30s — until terminal:

curl -s https://api.kreuzberg.dev/v1/documents/$DOC_ID/diff/$DIFF_JOB_ID \
  -H "Authorization: Bearer $KREUZBERG_API_KEY"

Treat both 200 (inline) and 202 (queued) as success at submit time; branch on the status code to decide whether to poll.

Errors

Other skills

• tracking-cloud-jobs — polling cadence and terminal-status detection (reuse it for async diff jobs).
• offloading-extraction — produces the document_id these endpoints read.

Source: hashgraph-online/awesome-codex-plugins → plugins/kreuzberg-dev/plugins/plugins/kreuzberg-cloud/skills/versioning-documents/SKILL.md