Extract your first document
Nugget turns documents into structured values with evidence. This guide uses the
same organization key for upload, extraction, and polling. Release v3 still
uses /v1/... URL paths.
Before you start
Obtain an organization API key from your Nugget dashboard. For a hosted account, configure that organization's provider credentials (BYOK) before using a model. Self-hosted provider access is configured by your deployment operator.
Set NUGGET_BASE_URL to your deployment's HTTPS origin (without /v1) and
NUGGET_API_KEY to your organization key. Keep the key server-side. The
x-api-key header is required on every operation below.
Model availability is organization-specific. Discover it rather than copying a model ID from an old example:
curl --fail-with-body "$NUGGET_BASE_URL/v1/models" \
-H "x-api-key: $NUGGET_API_KEY"
Choose a returned id and set NUGGET_MODEL to that exact value.
Complete Python workflow
Install httpx. This runnable example creates a tiny CSV fixture in memory,
uploads it, submits a typed JSON extraction request, and polls for at most five
minutes. CSV and XLSX evidence may have no bounding box.
import os
import time
import uuid
from urllib.parse import urljoin, urlsplit
import httpx
base = os.environ["NUGGET_BASE_URL"].rstrip("/")
model = os.environ["NUGGET_MODEL"]
headers = {"x-api-key": os.environ["NUGGET_API_KEY"]}
with httpx.Client(headers=headers, timeout=60, follow_redirects=False) as client:
upload = client.post(
base + "/v1/uploads",
files={"file": ("invoice.csv", b"customer,total\nAcme,125.50\n", "text/csv")},
)
upload.raise_for_status()
file_id = upload.json()["file_id"]
creation_key = str(uuid.uuid4()) # Persist and reuse for retries of this creation.
response = client.post(base + "/v1/extractions", headers={"Idempotency-Key": creation_key}, json={
"file_id": file_id,
"model": model,
"execution": "async",
"schema": {
"type": "object",
"properties": {
"customer": {"type": "string"},
"total": {"type": "number"},
},
},
})
response.raise_for_status()
assert response.status_code == 202
accepted = response.json()
status_url = urljoin(base + "/", accepted["status_url"])
if (urlsplit(status_url).scheme, urlsplit(status_url).netloc) != (urlsplit(base).scheme, urlsplit(base).netloc):
raise ValueError("Unexpected polling host")
deadline = time.monotonic() + 300
while time.monotonic() < deadline:
response = client.get(status_url)
response.raise_for_status()
job = response.json()
if job["status"] == "failed":
raise RuntimeError(job["error"])
if job["status"] == "succeeded":
result = job["result"]
print(result["data"]["customer"])
print(result["provenance"].get("/customer"))
break
time.sleep(2)
else:
raise TimeoutError(f"Stop polling; retain this URL to resume: {status_url}")
This example deliberately stops on HTTP failures instead of blindly retrying job creation. Production retry guidance is in Jobs and retries. An HTTP 200 polling response can still contain a failed job.
Complete TypeScript workflow
With Node 22+, save this as quickstart.ts and run it with npx tsx quickstart.ts.
Use the same environment variables as the Python example. This uses built-in
fetch; generated-client configuration is in the agent guide.
import process from "node:process";
import { randomUUID } from "node:crypto";
async function extract() {
const base = new URL(process.env.NUGGET_BASE_URL!);
const headers = { "x-api-key": process.env.NUGGET_API_KEY! };
const form = new FormData();
form.append("file", new Blob(["customer,total\nAcme,125.50\n"], { type: "text/csv" }), "invoice.csv");
const upload = await fetch(new URL("/v1/uploads", base), {
method: "POST", headers, body: form, redirect: "error", signal: AbortSignal.timeout(60000),
});
if (!upload.ok) throw Error(`Upload failed: ${upload.status}`);
const { file_id } = await upload.json();
const creationKey = randomUUID(); // Persist and reuse if this response is lost.
const accepted = await fetch(new URL("/v1/extractions", base), {
method: "POST", redirect: "error", signal: AbortSignal.timeout(60000),
headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": creationKey },
body: JSON.stringify({ file_id, model: process.env.NUGGET_MODEL, execution: "async",
schema: { type: "object", properties: { customer: { type: "string" } } } }),
});
if (accepted.status !== 202) throw Error(`Creation failed: ${accepted.status}`);
const { status_url } = await accepted.json();
const polling = new URL(status_url, base);
if (polling.origin !== base.origin) throw Error("Unexpected polling origin");
const deadline = Date.now() + 300000;
while (Date.now() < deadline) {
const response = await fetch(polling, { headers, redirect: "error", signal: AbortSignal.timeout(Math.min(60000, Math.max(1, deadline - Date.now()))) });
if (!response.ok) throw Error(`Polling failed: ${response.status}`);
const job = await response.json();
if (job.status === "failed") throw Error(JSON.stringify(job.error));
if (job.status === "succeeded") {
console.log(job.result.data.customer, job.result.provenance["/customer"]);
return;
}
await new Promise(resolve => setTimeout(resolve, 2000));
}
throw Error(`Polling deadline reached; retain this URL: ${polling}`);
}
void extract();
Submit with curl
After uploading, set FILE_ID to the returned file_id. With jq installed:
jq -n --arg file_id "$FILE_ID" --arg model "$NUGGET_MODEL" \
'{file_id:$file_id,model:$model,execution:"async",schema:{type:"object",properties:{customer:{type:"string"}}}}' |
curl --fail-with-body "$NUGGET_BASE_URL/v1/extractions" \
-H "x-api-key: $NUGGET_API_KEY" -H 'Content-Type: application/json' --data-binary @-
The response is 202 Accepted, not completed extraction. Resolve its
status_url against your deployment and GET it using the same key.
Fast inline work or explicit jobs
OCR, classification, and Locate accept execution: "auto" (the default) or
"async". Always inspect the status before interpreting the response body:
response = client.post(base + "/v1/ocr", json={"file_id": file_id, "execution": "auto"})
response.raise_for_status()
if response.status_code == 202:
accepted = response.json() # retain job_id and poll status_url
else:
ocr = response.json() # completed OcrResponse
The fragment above assumes an open authenticated client. Extraction currently
queues in both modes. A callback also selects async execution. Client metadata
alone does not.
Next steps
- Operation selection: choose the right endpoint.
- Schemas and provenance: understand values, errors, and evidence.
- Retention: understand source and result cleanup.
- ReDoc reference: complete argument and response schemas.
- OpenAPI: machine-readable contract for this deployment.