菜单
Use when the user wants to retrieve a stored document and its extraction result, list a document's versions, or diff two versions. Covers GET /v1/documents/{id}, GET /v1/documents/{id}/versions, and the sync-with-async-fallback diff at GET /v1/documents/{id}/diff plus its poll endpoint.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Use when extracting a page needs scripted interaction first — click, type, press a key, scroll, wait, screenshot, or run JS before capturing the DOM. Covers `crawlberg interact <url> --actions` with the real action schema, result shape, limits, and external-CDP options.
Crawl, scrape, and convert websites to Markdown using the local crawlberg CLI and its MCP server. Use when the user wants to fetch a page, follow links across a domain, enumerate URLs, or drive a real browser. Covers installation, the subcommands (scrape, crawl, map, interact, mcp, serve), output formats (JSON + Markdown), browser fallback, and when to prefer the MCP server over shelling out.
Use when the user wants to follow links across a domain and capture every reachable page as Markdown. Covers `crawlberg crawl` with depth, page caps, concurrency, rate limiting, domain scoping, robots, and output selection.
Use when a static fetch returns nothing useful and the page needs a real browser. Covers `--browser-mode auto|always|never`, external CDP via `--browser-endpoint`, symptoms of JS-only pages and WAF blocks, and the performance cost.
Use when the user wants the list of URLs on a site rather than the page content — sitemap analysis, link planning, or seeding another tool. Covers `crawlberg map <url>` with `--limit`, `--search`, robots, output, and how it differs from a full crawl.
Use when the user wants a single page rendered as clean Markdown plus structured metadata. Covers `crawlberg scrape <url>`, JSON vs Markdown output, what metadata is returned, and how to handle JS-heavy pages.
| name | versioning-documents |
| description | Use when the user wants to retrieve a stored document and its extraction result, list a document's versions, or diff two versions. Covers GET /v1/documents/{id}, GET /v1/documents/{id}/versions, and the sync-with-async-fallback diff at GET /v1/documents/{id}/diff plus its poll endpoint. |
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.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/documents/{document_id} | Latest version of a document with its extraction result. |
| GET | /v1/documents/{document_id}/versions | List all versions (paginated), newest first. |
| GET | /v1/documents/{document_id}/diff?from={v}&to={v} | Diff two versions — sync (200), async fallback (202) when over budget. |
| GET | /v1/documents/{document_id}/diff/{diff_job_id} | Poll an async diff job. |
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.
curl -s https://api.xberg.io/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).
curl -s https://api.xberg.io/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.
curl -s "https://api.xberg.io/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.
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.xberg.io/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.
| Status | Meaning | Action |
|---|---|---|
400 | Invalid from/to | Pass a version sequence integer or a job UUID. |
401 | Bad API key | Check the Authorization header. |
404 | Version not found | Document or version doesn't exist in this project. |
422 | Async diff failed | The queued diff errored server-side; resubmit or report. |
tracking-cloud-jobs — polling cadence and terminal-status detection (reuse it for async diff jobs).offloading-extraction — produces the document_id these endpoints read.