offloading-extraction
Use when the user wants to extract a document via the cloud rather than the local kreuzberg CLI. Covers POST /v1/extract — JSON vs multipart bodies, URL crawls, options block, webhook attachment, and the async response shape.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- offloading-extraction
- description
- Use when the user wants to extract a document via the cloud rather than the local kreuzberg CLI. Covers POST /v1/extract — JSON vs multipart bodies, URL crawls, options block, webhook attachment, and the async response shape.
03 SKILL.md 正文
Offloading extraction
POST /v1/extract is the single submit endpoint. It returns 202 Accepted
with job_ids (extraction) and crawl_job_ids (URL crawls) — never the
extraction result inline. Pair every submit with either a poll loop
(tracking-cloud-jobs skill) or a webhook.
When to reach for this
- File is on a remote URL.
- File is on disk but the local
kreuzbergCLI is not installed. - You want server-side parallelism for a batch.
- The user wants webhook-delivered results to skip blocking.
- File is larger than ~50 MB → use
presigned-uploadsinstead — the base64 JSON body is too big.
Endpoint
POST https://api.kreuzberg.dev/v1/extract
Authorization: Bearer $KREUZBERG_API_KEY
Content-Type: application/json | multipart/form-data
Returns 202 Accepted with ExtractResponse.
Three submission shapes
1. Base64 JSON (small files, <5 MB recommended)
curl -X POST https://api.kreuzberg.dev/v1/extract \
-H "Authorization: Bearer $KREUZBERG_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<JSON
{
"documents": [
{
"filename": "invoice.pdf",
"mime_type": "application/pdf",
"data": "$(base64 -w0 invoice.pdf)"
}
],
"options": {
"extraction_config": {
"output_format": "markdown",
"ocr": { "backend": "tesseract", "language": "eng" }
}
}
}
JSON
2. Multipart (binary, recommended for anything over ~1 MB)
curl -X POST https://api.kreuzberg.dev/v1/extract \
-H "Authorization: Bearer $KREUZBERG_API_KEY" \
-F "file=@invoice.pdf;type=application/pdf" \
-F 'options={"extraction_config":{"output_format":"markdown"}};type=application/json'
Add a webhook part as a JSON string:
-F 'webhook={"url":"https://hooks.example.com/x","secret":"shh"};type=application/json'
3. URL crawl
curl -X POST https://api.kreuzberg.dev/v1/extract \
-H "Authorization: Bearer $KREUZBERG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [{"url": "https://example.com/docs"}],
"crawl_config": {"max_depth": 2, "max_pages": 50, "stay_on_domain": true},
"webhook": {"url": "https://hooks.example.com/x"}
}'
URL crawls return crawl_job_ids instead of (or alongside) job_ids.
Response (202)
{
"job_ids": ["550e8400-e29b-41d4-a716-446655440000"],
"crawl_job_ids": [],
"status": "pending"
}
status is always pending at submit time; the per-job status is
retrieved via GET /v1/jobs/{id}.
The options block
Shape mirrors the local ExtractionConfig:
{
"extraction_config": {
"output_format": "markdown",
"ocr": { "backend": "tesseract", "language": "eng+deu" },
"extract_tables": true,
"extract_images": false,
"chunking": { "max_chars": 4000, "overlap": 200 }
}
}
Supported output_format values: markdown, text, json, djot,
html. Default is markdown.
The webhook block
{
"url": "https://hooks.example.com/x",
"secret": "shared-secret-32-bytes-min",
"metadata": { "request_id": "abc123", "user_id": "u_42" }
}
secret is the HMAC key used to sign the webhook payload — see
tracking-cloud-jobs for verification. metadata is echoed back in the
delivered payload, useful for correlating server-side requests.
TypeScript SDK
import { KreuzbergCloud } from "@kreuzberg/cloud";
import { readFile } from "node:fs/promises";
const client = new KreuzbergCloud({ apiKey: process.env.KREUZBERG_API_KEY! });
const data = await readFile("invoice.pdf");
const job = await client.extract({
file: { name: "invoice.pdf", data, mimeType: "application/pdf" },
options: { extractionConfig: { outputFormat: "markdown" } },
});
console.log(job.id, job.status);
For submit + wait in one call:
const result = await client.extractAndWait({
file: { name: "invoice.pdf", data },
});
console.log(result.result?.content);
Python SDK
from pathlib import Path
from kreuzberg_cloud import KreuzbergCloud
with KreuzbergCloud(api_key=os.environ["KREUZBERG_API_KEY"]) as client:
job = client.extract(file=Path("invoice.pdf"))
print(job.id, job.status)
Submit + wait:
job = client.extract_and_wait(file=Path("invoice.pdf"))
print(job.result.content if job.result else job.status)
Batch submission
JSON: pass multiple entries in documents. Multipart: repeat the file
part. SDKs expose extractBatch / extract_batch helpers that fan out
correctly per platform (parallel HTTP for the async Python client,
sequential for the sync one).
Errors
| Status | Cause | Fix |
|---|---|---|
400 |
Empty documents and urls |
Provide at least one. |
400 |
Bad MIME type | Use a real RFC 6838 type, e.g. application/pdf. |
401 |
Missing Bearer | Set Authorization header. |
413 |
Request body too large | Switch to presigned uploads. |
429 |
Quota or rate limit | Backoff; check quota_remaining via /v1/usage. |
Next step
After every submit, hand off to the tracking-cloud-jobs skill — cloud
extraction is asynchronous and the result is delivered via either polling
or webhook callback. Never assume a result is ready immediately after the
202 response.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.