Skip to main content
POST
Create a batch

Authorizations

X-API-KEY
string
header
required

Headers

Idempotency-Key
string | null

Body

application/json
source
FilesSource · object
required

The documents to process: {"type": "files", "file_ids": [...]} for previously-uploaded files, or {"type": "urls", "urls": [...]} to have us fetch each URL directly (no upload step; source bytes never written to our storage).

engine
string | null

Reserved for future engine selection. Leave unset; only the default engine is accepted today.

Maximum string length: 64
extract_text
boolean
default:true

Include text chunks in each item's result. Set false to skip text spans in every item.

extract_images
boolean
default:true

Include figure (image) chunks in each item's result. Set false to skip figure extraction in every item.

ocr
enum<string>
default:auto

Deprecated. Accepted for backward compatibility but currently has no effect.

Available options:
auto,
never,
force
table_output_format
enum<string>
default:markdown

How table chunks are structured in each item's result. 'markdown' (default) keeps the existing markdown-derived cells; 'cell_grid' returns true per-cell bounding boxes on table chunks.

Available options:
markdown,
cell_grid,
html
chunking
enum<string>
default:none

'none' (default): item results unchanged. 'semantic': each item's result additionally carries segments — elements grouped toward chunk_size characters at semantic/structural boundaries.

Available options:
none,
semantic
chunk_size
integer
default:1000

Target segment size in characters. Segments land in a +/-25% band around this target. Only meaningful when chunking is enabled; validated (200-8000) only in that case and ignored otherwise.

metadata
Metadata · object | null

Arbitrary JSON stored with the batch and echoed back on every poll, in the batch list, and in webhook event bodies. Put your own run ids, tenant ids, or job references here. It never affects processing. Maximum 16 KB serialized.

webhook
WebhookConfig · object | null

Optional completion webhook for this batch. Omitted means no webhook fires. {"mode": "svix"} delivers a signed batch.update event to your registered endpoints when the batch reaches a terminal status; {"mode": "direct", "url": ...} sends an unsigned event to the given HTTPS URL (prototyping).

Response

Successful Response

id
string
required
status
string
required
counts
BatchCounts · object
required
total_items
integer
required
engine
string | null
required
options
Options · object
required
created_at
string
required
expires_at
string
required
object
string
default:batch
metadata
Metadata · object | null
started_at
string | null
completed_at
string | null