Split a mixed scan
One PDF holds a two-page invoice, a receipt and a one-page invoice, scanned back to back. split finds where each document starts and ends and routes every piece to the extraction that fits it, so you get one extraction per document instead of one blurry one for the whole file.
The documents are synthetic (invented names, amounts and accounts), generated by
scripts/docs_examples.py:
The graph
parse → split
split → (invoices) extract_invoice
split → (receipts) extract_receipt
The full version body (graph and schemas), as the API takes it:
{
"graph": {
"nodes": [
{
"id": "parse",
"type": "parse"
},
{
"id": "split",
"type": "split",
"config": {
"rules": [
{
"id": "invoices",
"name": "Invoice",
"description": "An invoice, one or more pages"
},
{
"id": "receipts",
"name": "Receipt",
"description": "A till receipt"
}
]
}
},
{
"id": "extract_invoice",
"type": "extract",
"config": {
"schema_id": "invoice"
}
},
{
"id": "extract_receipt",
"type": "extract",
"config": {
"schema_id": "receipt"
}
}
],
"edges": [
{
"source": "parse",
"target": "split"
},
{
"source": "split",
"target": "extract_invoice",
"branch": "invoices"
},
{
"source": "split",
"target": "extract_receipt",
"branch": "receipts"
}
]
},
"schemas": {
"invoice": {
"type": "object",
"properties": {
"invoice_number": {
"type": "string"
},
"total": {
"type": "number"
}
}
},
"receipt": {
"type": "object",
"properties": {
"merchant_name": {
"type": "string"
},
"total": {
"type": "number"
}
}
}
}
}
Create it and run it
Set DX_BASE_URL and DX_API_KEY (see the quickstart), cd to
docs/examples/gallery/split-scan/ and run any of the three. They do the same.
Python
# SPDX-License-Identifier: Apache-2.0
# expect: "status": "succeeded"
"""Split a mixed scan: create the workflow, run it on the document and print what comes back."""
import json
import os
import secrets
from pathlib import Path
import httpx
api = httpx.Client(
base_url=os.environ["DX_BASE_URL"],
headers={"Authorization": f"Bearer {os.environ['DX_API_KEY']}"},
timeout=120,
)
name = f"split-scan-{secrets.token_hex(3)}" # unique, so the example can run again
# 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
workflow = api.post("/v1/workflows", json={"name": name}).raise_for_status().json()
version = (
api.post(
f"/v1/workflows/{workflow['id']}/versions",
json=json.loads(Path("workflow.json").read_text()),
)
.raise_for_status()
.json()
)
api.post(f"/v1/workflow-versions/{version['id']}:publish", json={}).raise_for_status()
api.put(
f"/v1/workflows/{workflow['id']}/aliases/prod", json={"version_id": version["id"]}
).raise_for_status()
# 2. Run it on the document and wait for the result.
run = (
api.post(
"/v1/runs",
data={"workflow": f"{name}@prod"},
files=[("files", ("scan.pdf", Path("scan.pdf").read_bytes(), "application/pdf"))],
)
.raise_for_status()
.json()
)
run = api.get(f"/v1/runs/{run['id']}", params={"wait": 60}).raise_for_status().json()
result = api.get(f"/v1/runs/{run['id']}/result").raise_for_status().json()
extracted = {
sid: scope["data"]
for node in result["outputs"]["extractions"].values()
for sid, scope in node["scopes"].items()
}
view = {
"status": run["status"],
"segments": [
{
"rule": s["rule_id"],
"pages": [p["packet_page"] for p in s["pages"]],
"data": extracted.get(s["id"]),
}
for s in result["outputs"]["segments"]["split"]
],
}
print(json.dumps(view, indent=2))
TypeScript
// SPDX-License-Identifier: Apache-2.0
// expect: "status": "succeeded"
// Split a mixed scan: create the workflow, run it on the document and print what comes back.
// Node 22+: node --experimental-strip-types create.ts
import { readFileSync } from "node:fs";
const base = process.env.DX_BASE_URL as string;
const auth = { Authorization: `Bearer ${process.env.DX_API_KEY}` };
const name = `split-scan-${Math.random().toString(16).slice(2, 8)}`; // unique, so it can run again
async function call(path: string, init: RequestInit = {}): Promise<any> {
const response = await fetch(base + path, { ...init, headers: { ...auth, ...init.headers } });
if (!response.ok) throw new Error(`${response.status} ${path}: ${await response.text()}`);
return response.json();
}
const json = (body: unknown): RequestInit => ({
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
// 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
const workflow = await call("/v1/workflows", json({ name }));
const version = await call(
`/v1/workflows/${workflow.id}/versions`,
json(JSON.parse(readFileSync("workflow.json", "utf8"))),
);
await call(`/v1/workflow-versions/${version.id}:publish`, json({}));
await call(`/v1/workflows/${workflow.id}/aliases/prod`, {
...json({ version_id: version.id }),
method: "PUT",
});
// 2. Run it on the document and wait for the result.
const form = new FormData();
form.append("workflow", `${name}@prod`);
form.append("files", new Blob([readFileSync("scan.pdf")], { type: "application/pdf" }), "scan.pdf");
const started = await call("/v1/runs", { method: "POST", body: form });
const run = await call(`/v1/runs/${started.id}?wait=60`);
const result = await call(`/v1/runs/${run.id}/result`);
const extracted: Record<string, any> = {};
for (const node of Object.values<any>(result.outputs.extractions)) {
for (const [sid, scope] of Object.entries<any>(node.scopes)) extracted[sid] = scope.data;
}
const view = {
status: run.status,
segments: result.outputs.segments.split.map((s: any) => ({
rule: s.rule_id,
pages: s.pages.map((p: any) => p.packet_page),
data: extracted[s.id] ?? null,
})),
};
console.log(JSON.stringify(view, null, 2));
curl
#!/usr/bin/env bash
# SPDX-License-Identifier: Apache-2.0
# expect: "status": "succeeded"
# Split a mixed scan: create the workflow, run it on the document and print what comes back.
# Needs curl and jq; DX_BASE_URL and DX_API_KEY in the environment.
set -euo pipefail
api() { curl -sS --fail-with-body -H "Authorization: Bearer $DX_API_KEY" "$@"; }
JSON='Content-Type: application/json'
NAME="split-scan-$RANDOM$RANDOM" # unique, so the example can run again
# 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
WORKFLOW=$(api -X POST "$DX_BASE_URL/v1/workflows" -H "$JSON" -d "{\"name\": \"$NAME\"}" | jq -r .id)
VERSION=$(api -X POST "$DX_BASE_URL/v1/workflows/$WORKFLOW/versions" -H "$JSON" -d @workflow.json | jq -r .id)
api -X POST "$DX_BASE_URL/v1/workflow-versions/$VERSION:publish" -H "$JSON" -d '{}' > /dev/null
api -X PUT "$DX_BASE_URL/v1/workflows/$WORKFLOW/aliases/prod" -H "$JSON" \
-d "{\"version_id\": \"$VERSION\"}" > /dev/null
# 2. Run it on the document and wait for the result.
RUN=$(api -X POST "$DX_BASE_URL/v1/runs" -F "workflow=$NAME@prod" -F "[email protected]" | jq -r .id)
STATUS=$(api "$DX_BASE_URL/v1/runs/$RUN?wait=60" | jq -r .status)
api "$DX_BASE_URL/v1/runs/$RUN/result" | jq --arg status "$STATUS" '([.outputs.extractions[].scopes | to_entries[] | {key, value: .value.data}] | from_entries) as $x | {status: $status, segments: [.outputs.segments.split[] | {rule: .rule_id, pages: [.pages[].packet_page], data: ($x[.id] // null)}]}'
Response
Produced by running the script above against a server with the fake model and these documents;
make docs runs all the examples again and fails if an answer changes.
{
"status": "succeeded",
"segments": [
{
"rule": "invoices",
"pages": [
1,
2
],
"data": {
"invoice_number": "INV-2026-0101",
"total": 640
}
},
{
"rule": "receipts",
"pages": [
3
],
"data": {
"merchant_name": "CAFE LUNA",
"total": 7.5
}
},
{
"rule": "invoices",
"pages": [
4
],
"data": {
"invoice_number": "INV-2026-0102",
"total": 90
}
}
]
}