Segment Document
Segment a document into sections using a schema. Returns page ranges for each identified segment. Provide a file for end-to-end processing, or a checkpoint_id from a previous /convert call.
Authorizations
Body
JSON object (passed as a string) defining how to segment the document. Keys: segmentation_strategy: document_boundary (split a combined file into its documents) or custom (find named sections); defaults to custom when segments is given, else document_boundary. segments: list of names or {name, description} objects; required for custom, not allowed with document_boundary. granularity: page returns page ranges and titles only, with no OCR parse, billed as segment only; block lets boundaries fall mid-page and returns parsed markdown (runs Convert); omitted returns page boundaries plus parsed markdown (runs Convert). prompt: optional free-text rule (up to 4,000 characters) for where one segment ends and the next begins, e.g. "start a new segment at each invoice" or "treat each email attachment as its own document". Used by document_boundary (page or omitted) and block segmentation; ignored when segments are given. Examples: {"segmentation_strategy": "document_boundary", "granularity": "page"}; {"granularity": "block", "prompt": "start a new segment at each invoice"}; {"segments": [{"name": "Indemnification"}]}. The same object (JSON-encoded) is used for segment steps in pipelines via settings.segmentation_schema.
Optional file URL. Provide either file/file_url or checkpoint_id.
Checkpoint ID from a previous /convert request (with save_checkpoint=true). Skips re-parsing when provided.
Output mode for parsing (only used when providing a file, not a checkpoint).
The maximum number of pages to process.
The page range to process, comma separated like 0,5-10,20.
Save a checkpoint after processing for future extraction/segmentation calls.
Skip the cache and re-run.
Optional webhook URL to call when the request is complete.
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.
Input PDF, word document, powerpoint, or image file, uploaded as multipart form data. Images must be png, jpg, or webp format.
Response
Successful Response
The ID of the request. This ID can be used to check the status of the request.
The URL to check the status of the request and get results.
Whether the request was successful.
If the request was not successful, this will contain an error message.
A dictionary of the versions of the libraries used in the request.
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.