Skip to main content
POST
Convert Document

Authorizations

X-API-Key
string
header
required

Cookies

wos-session
string
datalab_active_team
string

Body

multipart/form-data
file_url
string | null

Optional file URL (http/https). If provided, the server will download and process it.

mode
string
default:fast

Which output mode to use. Valid values: 'fast' (lowest latency), 'balanced' (balanced accuracy and latency), 'accurate' (highest accuracy).

max_pages
integer | null

The maximum number of pages in the document to convert.

page_range
string | null

The page range to convert, comma separated like 0,5-10,20. Overrides max_pages if provided.

merge_cross_page
boolean
default:false

Merge content that is split across pages back into single logical blocks: tables (long tables continued vertically, and wide tables printed as per-page column panels), paragraphs broken mid-sentence, and lists continued on the next page (continuation items keep the indent level of the list they belong to). Merged blocks carry a data-merged-pages attribute listing their source pages. Billed as a compute surcharge on the measured merge cost, like agent extraction.

paginate
boolean
default:false

Whether to paginate the output. Each page will be separated by a horizontal rule with the page number.

add_block_ids
boolean
default:false

Add data-block-id attributes to HTML elements for citation tracking. Only applies when output_format includes 'html'.

disable_html_prettify
boolean
default:false

Disable pretty-printing of the HTML output. By default the HTML is indented with each tag on its own line, which browsers render as visible extra spaces around inline tags (e.g. '( 23 )' instead of '(23)'). Set to True to receive compact HTML that renders exactly as parsed. Only applies when output_format includes 'html'.

include_markdown_in_chunks
boolean
default:false

Include markdown field in chunks and JSON output.

disable_image_extraction
boolean
default:false

Disable image extraction from the document.

disable_image_captions
boolean
default:false

Disable synthetic image captions/descriptions in output.

word_bboxes
boolean
default:false

When enabled, predict per-word bounding boxes with confidence scores for each page. Each word is inlined into the HTML output as a span carrying data-bbox and data-confidence attributes (markdown output strips these).

fence_synthetic_captions
boolean
default:false

Wrap synthetic image captions with HTML comment markers for easy identification/removal.

output_format
string | null

The output format. Can be 'json', 'html', 'markdown', or 'chunks'. Defaults to 'markdown'. Comma separate multiple formats.

token_efficient_markdown
boolean
default:false

Optimize markdown for LLM token usage (compact tables, single-space indents).

skip_cache
boolean
default:false

Skip the cache and re-run the conversion.

save_checkpoint
boolean
default:false

Save a checkpoint after conversion. The checkpoint_id in the response can be used with /extract or /segment to skip re-parsing.

additional_config
string | null

Additional configuration as a JSON string. Supported keys: 'keep_pageheader_in_output', 'keep_pagefooter_in_output', 'keep_spreadsheet_formatting'.

extras
string | null

Comma-separated list of extra features to enable. Currently supports: 'track_changes', 'chart_understanding', 'table_cell_bboxes' (per-cell bounding boxes for each table, instead of one box for the whole table; includes word bounding boxes), 'list_item_bboxes' (per-item bounding boxes for each list or list group, instead of one box for the whole list; includes word bounding boxes), 'extract_links', 'extract_bookmarks' (PDF outline/bookmark tree in metadata.pdf_bookmarks; safety-limit truncation is reported by metadata.pdf_bookmarks_truncated), 'infographic', 'new_block_types'.

webhook_url
string | null

Optional webhook URL to call when the request is complete.

processing_location
string | null

Optional residency region override (e.g. us, eu). When provided, use file_url or direct-upload; multipart uploads are rejected. When omitted, the request uses the team's configured residency and profile.

eval_rubric_id
integer | null

Optional eval rubric ID to run evaluation after conversion.

model_override_settings
string | null
file
file | null

Input PDF, word document, powerpoint, or image file, uploaded as multipart form data. Images must be png, jpg, or webp format.

Response

Successful Response

request_id
string
required

The ID of the request. This ID can be used to check the status of the request.

request_check_url
string
required

The URL to check the status of the request and get results.

success
boolean
default:true

Whether the request was successful.

error
string | null

If the request was not successful, this will contain an error message.

versions

A dictionary of the versions of the libraries used in the request.

checkpoint_reused
boolean | null

True when this run automatically reused a checkpoint from a previous run of the same file, so the conversion step is not re-billed. Absent/None otherwise.