New batch

Use the workspace API

This API uses your signed-in browser session on this site; customer API keys and external token access are not available.

Use relative paths from a page on this origin with credentials: 'same-origin'. Private records and downloads are scoped to your account. Do not share session cookies or move them into scripts on other sites.

Authenticate requests

• GET /v1/csrf returns csrf_token and sets the CSRF cookie. Send that token as X-CSRFToken on every POST or DELETE. JSON bodies need Content-Type: application/json; let the browser set multipart boundaries for FormData.
• POST /v1/auth/login accepts {username, password} and returns authenticated; POST /v1/auth/logout ends the session. Both require CSRF. Prefer the sign-in page; refresh the CSRF token after signing in.
• Operations marked † require Idempotency-Key: 8–128 characters from A–Z a–z 0–9 . _ : -. Use a new key per operation and reuse the same key and body for an uncertain retry. Staging files is not idempotent: inspect the draft before retrying an upload. Checkout creation is also not idempotent: check payment history before retrying.

Stage files & review quotes

Replace {batch_id}, {job_id} and {document_id} with returned UUIDs. Item IDs and page numbers are integers. These are registered routes, not a promise that admission is open.

• GET / POST /v1/batches — GET lists drafts as items; POST with {} creates an empty draft (201).
• GET /v1/batches/{batch_id} — read batch_id, state, revision, expires_at, items, total_pages, can_submit.
• POST /v1/batches/{batch_id}/files — stage repeated multipart file fields: PDF, PNG, JPG/JPEG or flat ZIP. Returns the updated draft (201); does not start OCR.
• DELETE /v1/batches/{batch_id}/files/{item_id} — remove an item from an open draft; returns the updated draft.
• POST /v1/batches/{batch_id}/quote — JSON {revision, tier, retention_days, delete_after_receipt}; returns quote_id, page_count, max_micro_usd, rate_micro_usd, expires_at, revision (201). Use batch (24h) or batch_6h (2h). The tier identifier is unchanged. Miss the promised turnaround? We credit 50% of that job's final bill. Each billed job uses its own promised SLA; jobs with a zero final bill earn no late credit. Retention is 1–90 integer days; deletion choice is boolean.
• POST /v1/batches/{batch_id}/submit † — JSON {quote_id, revision}; returns job_id, state, reserved_micro_usd (201). A quote expires after 15 minutes; changing membership requires a new quote. Submission reserves credits, not a final charge.

Track jobs & retrieve results

• GET /v1/jobs — list your jobs as items.
• GET /v1/jobs/{job_id} — read state, progress, charge_micro_usd, reserved_micro_usd, expires_at, receipt_manifest.
• GET /v1/jobs/{job_id}/results — optional ?limit=25&after= cursor; returns items, next_cursor, has_more. Pass next_cursor as URL-encoded after on the next request; limit is 1–100. Each item includes document/page mapping and authenticated artifact URLs.
• GET /v1/jobs/{job_id}/pages/{page_no}/artifacts/{kind} — download a succeeded, retained page; kind is json, markdown or preview.
• GET /v1/jobs/{job_id}/manifest — read the whole-job artifact listing and hashes; GET /v1/jobs/{job_id}/download — download the ZIP. Both require all pages terminal and results unexpired. Downloading does not acknowledge receipt or delete files.
• POST /v1/jobs/{job_id}/cancel † — JSON {}; returns job_id, state (202). Processed pages may still be charged.
• POST /v1/jobs/{job_id}/retry † — JSON {pages: [2, 5]}, 1–100 failed page numbers; returns job_id, state, due_at, expires_at, reserved_micro_usd (202), subject to credit, attempts and retention.
• POST /v1/jobs/{job_id}/retention — JSON {retention_days: 30}; returns expires_at. Applies only to terminal, unexpired results, measured from original completion; cannot revive deleted/expired files.
• POST /v1/jobs/{job_id}/receipt — for instant-delete jobs only: JSON {confirm_receipt: true, confirm_delete_all_job_files: true, retry_cycle, manifest_sha256}. Use the current receipt_manifest.retry_cycle and receipt_manifest.sha256 from job details, not the ZIP manifest. Only confirm after saving and verifying all succeeded outputs. Queues deletion of all job files (202); the no-confirmation fallback is 24 hours from original completion.

Read balance & payment history

• GET /v1/wallet — currency, available_micro_usd, held_micro_usd, entries. Credit amounts are integer micro-USD: 1,000,000 = USD 1.00.
• GET /v1/wallet/transactions — payment items with payment_id, amount_minor, currency, state. Payment amounts use currency minor units, not micro-USD.
• GET / POST /v1/wallet/checkouts — GET reads packages and checkout_available (no sign-in required). POST requires a session and JSON {package_id}; returns checkout data with state: pending (201) only when checkout is configured. Use the billing view to complete checkout; a browser return does not credit your wallet.
• GET / POST /v1/wallet/refunds — GET reads request items; POST † with JSON {payment_id, reason} records an eligible request (202), not a completed refund. Reason: duplicate, service_issue or other.

Try a safe same-origin request

Run this in the browser console on this site after signing in. It creates an empty draft only: no upload, processing, reservation or charge.

const csrfResponse = await fetch('/v1/csrf', {credentials: 'same-origin'});
if (!csrfResponse.ok) throw new Error(`CSRF HTTP ${csrfResponse.status}`);
const {csrf_token} = await csrfResponse.json();
const response = await fetch('/v1/batches', {
  method: 'POST', credentials: 'same-origin',
  headers: {'Content-Type': 'application/json', 'X-CSRFToken': csrf_token},
  body: JSON.stringify({})
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const draft = await response.json();
console.log(draft.batch_id, draft.revision);

Respect limits & handle errors

Drafts expire after 24 hours. A submitted batch needs 30–2,000 validated pages; images count as one. Limits: 512 MiB per uploaded file or ZIP, 2 GiB total staged bytes, 2,000 staged items and 100 multipart files per request. ZIPs must be flat, unencrypted and contain only supported document types. Whole-job delivery is bounded to 20 MiB per artifact and 512 MiB total. Lists return at most 100 records; only incremental results use the cursor described above.

Default quota: 120 requests per 900 seconds per account, shared across customer routes (anonymous traffic uses the source IP). Deployment limits may differ. CSRF requests are exempt. Sign-in additionally limits attempts to 10 per identity and 30 per IP in 900 seconds. On 429, wait for Retry-After when present; avoid rapid polling.

Staging may return ADMISSION_CLOSED; submission may return CAPACITY_CLOSED or QUEUE_CAPACITY. Validation, available credit and configured checkout remain separate gates. Reading existing records does not enable processing.

• 400 — invalid body/options/cursor or missing idempotency key; 401 — sign in; 403 — missing/invalid CSRF (may be HTML, not JSON); 404 — not found in your account, or artifact not ready.
• 409 — stale quote/revision, conflicting key, insufficient credit or operation not allowed in this state. Refresh before retrying. 410 — results expired/deletion pending; 413 / 422 — size or validation limit; 429 — rate limit; 503 — admission/capacity/checkout unavailable; 500 ARTIFACT_INTEGRITY — do not trust the download; contact support.

Application errors usually contain error: {code, message, request_id, retryable}; rate-limit errors may omit the last two fields. Check HTTP status before parsing JSON. Contact account support with the request reference, never source documents or extracted text.