Skip to main content
POST

Overview

The v2 presigned upload endpoint decouples document delivery from job creation. Instead of uploading your file through the API server, you:
  1. POST to /v2/parse/upload with your configuration: the API creates a parse job and returns a short-lived presigned URL.
  2. PUT your file directly to the presigned URL: the API server is never in the transfer path.
  3. Once the upload completes, the job is automatically enqueued for processing.
  4. Poll GET /parse/{job_id} to track progress and retrieve results (the same endpoint as the standard Parse flow).
Use this flow when a file is too large to upload directly to the standard Parse Document endpoint. For documents that fit in a direct upload, use POST /parse, or POST /parse/excel for XLS and XLSX workbooks. Excel workbooks uploaded through this flow are processed by the Excel pipeline automatically.
The job status starts as AwaitingUpload. It transitions to Queued once the upload completes, then to Processing, and finally Succeeded or Failed. See Get Parse Job Status for the full response schema and polling examples.

Request

string
required
File name with extension (e.g. "report.pdf"). Determines the MIME type for the presigned URL and selects the Excel pipeline for XLS and XLSX names. Supported formats: PDF, images (PNG, JPG/JPEG, TIFF/TIF, WebP), office documents (DOC, DOCX, PPT, PPTX, XLS, XLSX), and HTML (HTML/HTM).
string
Processing mode preset: fast (Fast), agentic_lite (Agentic Lite), or agentic (Agentic). Each mode applies a recommended processing configuration that trades speed for fidelity. Parameters you send explicitly take precedence over the mode. See Processing Modes. Omit to use the default configuration.
boolean
Strikethrough detection: detects and preserves strikethrough formatting in HTML and Markdown output. Defaults to false.
boolean
Cross-page table consolidation: detects and combines table segments across page breaks. Reconstructs complete table structure by matching headers and columns. Defaults to false.
boolean
Reorder detected segments to follow the document’s natural reading order. Recommended for multi-column layouts (newspapers, two- or three-column papers) where text can otherwise interleave across columns. Defaults to false.
boolean
Run a PII pre-check before parsing. If PII is found, the task is rejected without parsing. Defaults to false.
Attach hyperlink URLs from PDF annotations to OCR results. Defaults to false.
boolean
Transfer text color from the PDF text layer to OCR results. Defaults to false.
string
Digitize charts into the numbers they were drawn from. One of:
  • "basic" (default): no chart data. Picture segments keep their usual description.
  • "standard": fast and accurate chart data extraction.
  • "advanced": for the most complex and messiest charts. Contact support to have this feature enabled for your organization; until it is, a request with advanced returns 403 with error.code set to feature_not_enabled.
chart_data includes chart_type, chart_title, x_label, y_label, legend, confidence, metadata, and data: an object keyed by series name, each series a list of {"x": ..., "y": ...} points. It is attached only when the chart’s values were recovered; when it is, the segment’s markdown and html show the chart’s data as a summary and one table per series. Otherwise the segment keeps its description and has no chart_data.The Agentic (agentic) processing mode uses standard unless you set this field.
boolean
Citation extraction: extracts academic citations from PDF documents and hyperlinks them in the markdown output. Generates structured bibliography metadata. PDFs only. Defaults to false.
string
Specify which pages to process. Leave empty to process all pages.Examples: "1-5" (pages 1 to 5), "2,4,6" (specific pages), "[1,3,5]" (array format), "1-3,7,10-15" (combination).
integer
Seconds the returned presigned upload URL stays valid. Defaults to 15 minutes (900 seconds). Once the client uploads the file, the task’s expiry is cleared and the task lifetime is no longer bounded by this value.
array
Export format(s) to generate after processing. Supported: ["docx", "markdown", "json"]. The exported files are available via the exports field in the task response.
string
Comma-separated segment types to keep in the output, or "all" to include every type. Defaults to "all".
array
Segment validation: uses a vision model to validate and correct segment types, fixing misclassified segments. Example: ["Table", "Formula", "Picture"]. Defaults to ["Table", "Picture"]; an empty or unparseable value also falls back to that default, so Table and Picture validation runs even when this field is omitted.
object
Configure how different segment types are processed: HTML/Markdown generation and custom VLM prompts.
On this endpoint the field is named segment_processing. The standard endpoint field segment_analysis is not accepted here and is silently ignored.
Options per segment type:
  • html / markdown: "VLM" (use a VLM to generate the output) or "Auto" (skip the VLM call and build from the OCR/recognized text)
  • vlm: Custom prompt for the VLM model. Use this to give the model specific instructions for extracting or describing these segment types.
Defaults are not uniform across segment types. Table.html, Picture.markdown, Formula.markdown, KeyValuePair.markdown, and both Page strategies default to "VLM"; everything else defaults to "Auto". If you want a Picture segment’s Markdown to contain only the transcribed text (rather than a VLM-written description), pass {"Picture": {"markdown": "Auto"}}.
KeyValuePair is configurable here too (form-field regions, produced for form documents). It returns an image crop URL alongside the text.For full details, see Parse Document.
object
JSON object controlling which fields are included in the output. Set fields to false to exclude them and reduce response size. Available fields: html, markdown, ocr, image, content, bbox, confidence, embed, chart_data. All default to true.
string
How to handle per-page errors during processing. "Continue" (default) skips failed pages and continues processing the rest. "Fail" aborts the entire job on the first error.

Response

string
Unique identifier for the parse job. Use this with GET /parse/{job_id} to poll status and retrieve results.
string
Presigned PUT URL. Upload your file directly to this URL; no api-key header is needed for the upload itself. Valid until expires_at.
string
RFC 3339 timestamp when upload_url expires. Upload must complete before this time. The presigned URL is valid for 15 minutes by default; when expires_in is set (and positive), the upload URL lifetime is set to that same value, which can shorten or extend the window.
string
Always "PUT". Use an HTTP PUT request when uploading to upload_url.
object
Key-value headers you MUST include in your PUT request. Always includes Content-Type set to the MIME type inferred from file_name.
integer
Number of page credits deducted as an initial reservation, reconciled on upload.
integer
Remaining page credits after deduction.

Step-by-Step Guide

Step 1: Create the parse job

POST to /v2/parse/upload with your file name and configuration. The API returns a job_id and a short-lived presigned URL.
The response contains the presigned URL and required headers:

Step 2: Upload the file

Use the upload_url and upload_headers from the response to PUT your file. No API key is needed for this request.
You must include every header listed in upload_headers. A missing or mismatched Content-Type will cause the upload to be rejected with a 403.

Step 3: Poll for results

Once the upload completes, the job transitions from AwaitingUpload → Queued → Processing → Succeeded. Poll the job through the standard GET /parse/{job_id} endpoint.
See Get Parse Job Status for the full response schema.

Standard and Large-File Upload Flows

Error Handling

A job can move from Queued straight to Failed without ever reaching Processing: after the upload, the document is page-counted and rejected if it exceeds the page limit (default 2000 pages; split large documents first) or if the remaining page quota cannot cover it.

Authorizations

Authorization
string
header
required

API key for authentication. Use 'Bearer <your_api_key>'

Body

application/json

Request body for POST /v2/parse/upload. Configuration fields mirror the existing /parse multipart form fields.

file_name
string
required

File name with extension. Required. Determines content-type.

detect_pii
boolean | null
default:false

Run a PII pre-check before parsing. When enabled, the document is scanned for personally identifiable information before any extraction work happens. If PII is found, the task is rejected and no parsing occurs (the job ends in a failed state with a PII reason). Defaults to false.

enhance_reading_order
boolean | null

Reorder detected segments to follow the document's natural reading order. Useful for multi-column layouts (newspapers, two- or three-column papers). Defaults to false.

error_handling
string | null

Error handling strategy: Continue (default) or Fail.

expires_in
integer<int32> | null

Seconds the returned presigned upload URL stays valid. Defaults to the PRESIGNED_UPLOAD_EXPIRY_SECS env value (typically 900 / 15 min). Once the client uploads the file, the task's expires_at is cleared and the task lifetime is no longer bounded by this value.

export_format
enum<string>[] | null

Export format(s) to generate after processing. Supported: ["docx", "markdown", "json"].

File format for exporting parsed results. When specified in a parse request, the pipeline generates the requested export file after processing completes. The exported file is available via the exports field in the task response.

Available options:
docx,
markdown,
json
extract_colors
boolean | null

Transfer text color from the PDF text layer to OCR results. Defaults to false.

Attach hyperlink URLs from PDF annotations to OCR results. Defaults to false.

extract_strikethrough
boolean | null

Preserve strikethrough formatting in HTML/Markdown output. Defaults to false.

merge_tables
boolean | null

Merge tables that span multiple pages into a single unified structure. Defaults to false.

output_fields
any

JSON object filtering which fields appear on each segment / chunk. Each key defaults to true; set a key to false to drop the field. Keys: bbox, chart_data, confidence, content, embed, html, image, markdown, ocr.

page_range
string | null

Page range to process. Formats: "1-5", "2,4,6", "[1,3,5]". Defaults to all pages.

segment_filter
string | null

Segment filter: comma-separated segment types to keep, or "all". Defaults to "all".

segment_processing
any

JSON object for segment processing/analysis configuration.

validate_segments
any

JSON array of segment types to validate with VLM. Example: ["Table","Formula"].

extract_charts
enum<string> | null
default:basic

Digitize charts into the numbers they were drawn from, attached to the Picture segment as chart_data. basic (default): no chart data. standard: fast and accurate chart data extraction. advanced: for the most complex and messiest charts; contact support to have it enabled for your organization (otherwise 403 with error.code = feature_not_enabled).

Available options:
basic,
standard,
advanced
xml_citation
boolean | null

Extract and hyperlink bibliography citations in the markdown output. Defaults to false.

mode
enum<string> | null

Processing mode preset. fast (Fast), agentic_lite (Agentic Lite), or agentic (Agentic). Each mode applies a recommended processing configuration; see Processing Modes. Parameters you send explicitly take precedence over the mode. Omit to use the default configuration.

Available options:
fast,
agentic_lite,
agentic

Response

Upload URL created

Response from POST /v2/parse/upload.

credit_used
integer<int32>
required

Number of page credits deducted (initial reservation, reconciled on upload).

expires_at
string
required

RFC 3339 timestamp when upload_url expires.

job_id
string
required

Use this ID to poll GET /parse/{job_id} for status.

quota_remaining
integer<int32>
required

Remaining page credits after deduction.

upload_headers
object
required

Headers the client MUST include in the PUT request.

upload_method
string
required

Always "PUT".

upload_url
string
required

S3 presigned PUT URL. Valid until expires_at.