Processing Documents

This page is a practical guide for how to think about using POST /v1/process in production (what to pass, what defaults mean, and what to do next). For exact request formats, see the Quickstart and API Reference.

Overview

The POST /v1/process endpoint accepts documents via file upload (multipart/form-data), processes them asynchronously as background jobs, and returns a job ID immediately.

Where to start

• Quickstart: /docs
• API Reference: POST /v1/process

How to choose what you send

schema, blueprint_id, or neither

• Send neither when you want the document as Markdown with layout and bounding boxes and no fields (Extract).
• Send schema when you're starting out or your extraction shape changes frequently (Extract).
• Send blueprint_id when you want a stable, reusable schema the optimizer tuned for a known document type (Extract; Standard and Enterprise plans).

Never send both schema and blueprint_id in one request. Whichever you send, pipeline=deep-extract runs Deep Extract.

speed

• Default: normal speed (speed=standard).
• Plans: speed=fast is available on Standard and Enterprise; a Free account gets 402.
• speed=fast with pipeline=deep-extract runs Deep Extract Fast: about 2x faster, same accuracy, $90 per 1,000 pages instead of $35.
• speed=fast with pipeline=extract costs nothing extra: Extract is already fast, so it stays at the Extract price ($15 per 1,000 pages). A short document takes the same time; long documents with big tables (40+ pages) are about 2x faster.
• How long: a 1–2 page document takes about 13 s on Extract, 1 min 26 s on Deep Extract and 38 s on Deep Extract Fast (medians from our benchmarks).

preview and HIL previews

• Default: preview=false
• What it does: controls whether DeepRead stores page images and returns a shareable preview_url for the HIL interface.
• Note: when preview=true, DeepRead will automatically include per-page results needed for previews (so you can expect per-page data in results).
• Privacy: the preview link is readable by anyone who has it, so nothing is stored or linked unless you send preview=true.

Response

The API returns immediately with a job ID:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Save the id to check job status manually or reference it in your webhook handler. The actual processing happens asynchronously in the background.

What happens next

1. Job is queued: Status is queued, processing hasn't started yet
2. Processing begins: Status changes to processing
3. Completion: Status becomes completed or failed
4. Webhook notification: If you provided webhook_url, DeepRead sends a POST request to your endpoint with the job result (see Handling Results)
5. Manual status and result check: Alternatively, use GET /v1/jobs/{job_id} to check status (see API Reference)
6. Dashboard: View all your jobs, filter by status/date, and access results from the Jobs page

Schema guidance

If you're passing schema, it must be a valid JSON Schema object. See Schemas for schema design guidance.

Webhook configuration

Including webhook_url is recommended for production use. DeepRead will send an HTTP POST request to your endpoint when the job completes or fails. See Handling Results for implementation details.

Webhooks are on the Standard and Enterprise plans; sending webhook_url on Free returns 402 naming the plan. If you don't provide a webhook URL, check GET /v1/jobs/{job_id} or the Jobs page to retrieve results.