Submit uploaded files as one batch job. Returns immediately with status: "pending"; poll GET /v1/batches/{batch_id} for per-item progress. Pass an Idempotency-Key header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.
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).
FilesSource
UrlSource
Show child attributes
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).
Show child attributes
Response
Successful Response
id
string
required
status
string
required
counts
BatchCounts · object
required
Show child attributes
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
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Hanji","description":"Parse documents into structured data.","colors":{"primary":"#0c0c0c","light":"#bad9f9","dark":"#0c0c0c"},"logo":{"light":"https://mintcdn.com/youlearn-b6958d02/Jy2a4ZjGgDJm0OsT/logo/light.svg?fit=max\u0026auto=format\u0026n=Jy2a4ZjGgDJm0OsT\u0026q=85\u0026s=04213e4d86750738bd50b582e537d2f0","dark":"https://mintcdn.com/youlearn-b6958d02/Jy2a4ZjGgDJm0OsT/logo/dark.svg?fit=max\u0026auto=format\u0026n=Jy2a4ZjGgDJm0OsT\u0026q=85\u0026s=370d162c81e2d402f59f68acea82d58c","href":"https://hanji.dev"},"favicon":"https://mintcdn.com/youlearn-b6958d02/Jy2a4ZjGgDJm0OsT/favicon.png?fit=max\u0026auto=format\u0026n=Jy2a4ZjGgDJm0OsT\u0026q=85\u0026s=49c5b072151a07aebb3757e4c2ccb387","api":{"playground":{"display":"interactive"}},"appearance":{"default":"light","strict":true},"background":{},"navbar":{"links":[{"href":"https://hanji.dev/pricing","label":"Pricing"},{"href":"https://hanji.dev/login","label":"Login"}],"primary":{"type":"button","label":"Get started","href":"https://hanji.dev/signup"}},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"metadata":{"timestamp":false},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"youlearn-b6958d02","hasAudioNarration":false,"actualSubdomain":"youlearn-b6958d02","customDomains":["docs.hanji.dev"],"gitSource":{"type":"github","owner":"youlearn-ai","repo":"extract","deployBranch":"main","contentDirectory":"mintlify","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ae9558fe37977b6234dee40:success","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Async batch","count":8},{"language":"default","tag":"Guides","count":3},{"language":"default","tag":"Schema extraction","count":2},{"language":"default","tag":"Parse (sync)","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"@layer base{a.card,.card.card{transition:background-color 150ms ease}a.card:hover,.card.card:hover{border-color:rgb(3 7 18 / 0.1)!important;background-color:rgb(3 7 18 / 0.04)!important}.dark a.card:hover,.dark .card.card:hover{border-color:rgb(255 255 255 / 0.1)!important;background-color:rgb(255 255 255 / 0.06)!important}}"}]}
{"page":{"pagePath":"api-reference/v1/create-a-batch","slug":"/api-reference/v1/create-a-batch","pageMetadata":{"title":"Create a batch","description":"Submit uploaded files as one batch job. Returns immediately with `status: \"pending\"`; poll `GET /v1/batches/{batch_id}` for per-item progress. Pass an `Idempotency-Key` header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/batches","href":"/api-reference/v1/create-a-batch","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Submit uploaded files as one batch job. Returns immediately with \", _jsx(_components.code, {\n children: \"status: \\\"pending\\\"\"\n }), \"; poll \", _jsx(_components.code, {\n children: \"GET /v1/batches/{batch_id}\"\n }), \" for per-item progress. Pass an \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \" header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Create a batch","description":"Submit uploaded files as one batch job. Returns immediately with `status: \"pending\"`; poll `GET /v1/batches/{batch_id}` for per-item progress. Pass an `Idempotency-Key` header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/batches","href":"/api-reference/v1/create-a-batch","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["v1","async-batch"],"summary":"Create a batch","description":"Submit uploaded files as one batch job. Returns immediately with `status: \"pending\"`; poll `GET /v1/batches/{batch_id}` for per-item progress. Pass an `Idempotency-Key` header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.","operationId":"create_batch_v1","security":["86843a74-e40d-40e2-aac8-9ef493aacd0c"],"parameters":["6b46c020-94ce-4e73-b9a9-e2ec8fe13261"],"requestBody":"dc34fa9b-1efd-455d-a637-0e6350b2042e","responses":{"200":"c99ae058-5b43-43d6-abb0-56c248c2e632","402":"d9a92c24-b5b8-48e9-bbb9-fa42909cb1ca","404":"3537d09e-e43a-424f-a987-63d377d5debb","409":"544eff09-c8ee-45e3-b0d0-94207937fb23","422":"ee48d8ee-f806-438f-85f9-1cbdabdec807"},"method":"post","type":"path","servers":["dd30c128-e109-412d-8b2e-00d772db84e5"],"path":"/v1/batches","baseUrlOptions":["https://api.hanji.dev"],"title":"Create a batch","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"6b46c020-94ce-4e73-b9a9-e2ec8fe13261":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"oneOf":[{"type":"string","title":"Idempotency-Key","uniqueKey":"oneOf.0","typeLabel":"string"},{"type":"null","title":"Idempotency-Key","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string | null"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"source":{"oneOf":[{"type":"object","title":"FilesSource","description":"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).","required":["file_ids"],"properties":{"file_ids":{"items":{"type":"string","uniqueKey":"source.oneOf.0.file_ids.items.[INDEX]","typeLabel":"string"},"type":"array","maxItems":10000,"minItems":1,"title":"File Ids","description":"Uploaded file ids (from POST /v1/files) to process, 1-10,000 per batch.","isRequired":true,"uniqueKey":"source.oneOf.0.file_ids","typeLabel":"string[]"},"type":{"type":"string","const":"files","title":"Type","default":"files","uniqueKey":"source.oneOf.0.type","typeLabel":"string"}},"isRequired":true,"uniqueKey":"source.oneOf.0","typeLabel":"FilesSource · object"},{"type":"object","title":"UrlSource","description":"Public or presigned URLs — no upload step. Source bytes are never\nwritten to our storage; only the extraction result is. Presigned URLs\nwork the same as public ones — pass the full URL through unmodified,\nincluding its signature query string.","required":["urls"],"properties":{"urls":{"items":{"type":"string","uniqueKey":"source.oneOf.1.urls.items.[INDEX]","typeLabel":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Urls","description":"Public or presigned HTTP(S) URLs to fetch and process, 1-100 per batch. Each URL becomes one item; we fetch it when that item starts processing, not when you submit the batch — a slow or large download doesn't block this request.","isRequired":true,"uniqueKey":"source.oneOf.1.urls","typeLabel":"string[]"},"type":{"type":"string","const":"urls","title":"Type","default":"urls","uniqueKey":"source.oneOf.1.type","typeLabel":"string"}},"isRequired":true,"uniqueKey":"source.oneOf.1","typeLabel":"UrlSource · object"}],"isRequired":true,"uniqueKey":"source","typeLabel":"FilesSource · object | UrlSource · object"},"engine":{"oneOf":[{"type":"string","title":"Engine","description":"Reserved for future engine selection. Leave unset; only the default engine is accepted today.","maxLength":64,"uniqueKey":"engine.oneOf.0","typeLabel":"string"},{"type":"null","title":"Engine","description":"Reserved for future engine selection. Leave unset; only the default engine is accepted today.","uniqueKey":"engine.oneOf.1","typeLabel":"null"}],"uniqueKey":"engine","typeLabel":"string | null"},"extract_text":{"type":"boolean","title":"Extract Text","description":"Include text chunks in each item's result. Set false to skip text spans in every item.","default":true,"uniqueKey":"extract_text","typeLabel":"boolean"},"extract_images":{"type":"boolean","title":"Extract Images","description":"Include figure (image) chunks in each item's result. Set false to skip figure extraction in every item.","default":true,"uniqueKey":"extract_images","typeLabel":"boolean"},"ocr":{"type":"string","enum":["auto","never","force"],"title":"Ocr","description":"Deprecated. Accepted for backward compatibility but currently has no effect.","default":"auto","uniqueKey":"ocr","typeLabel":"enum\u003cstring>"},"table_output_format":{"type":"string","enum":["markdown","cell_grid","html"],"title":"Table Output Format","description":"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.","default":"markdown","uniqueKey":"table_output_format","typeLabel":"enum\u003cstring>"},"chunking":{"type":"string","enum":["none","semantic"],"title":"Chunking","description":"'none' (default): item results unchanged. 'semantic': each item's result additionally carries `segments` — elements grouped toward chunk_size characters at semantic/structural boundaries.","default":"none","uniqueKey":"chunking","typeLabel":"enum\u003cstring>"},"chunk_size":{"type":"integer","title":"Chunk Size","description":"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.","default":1000,"uniqueKey":"chunk_size","typeLabel":"integer"},"metadata":{"oneOf":[{"type":"object","title":"Metadata","description":"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.","additionalProperties":true,"uniqueKey":"metadata.oneOf.0","typeLabel":"Metadata · object"},{"type":"null","title":"Metadata","description":"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.","uniqueKey":"metadata.oneOf.1","typeLabel":"null"}],"uniqueKey":"metadata","typeLabel":"Metadata · object | null"},"webhook":{"oneOf":[{"type":"object","title":"WebhookConfig","description":"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).","required":["mode"],"properties":{"mode":{"type":"string","enum":["svix","registered","direct","disabled"],"title":"Mode","description":"\"svix\": signed delivery to your registered endpoints. \"direct\": unsigned delivery to `url` (prototyping). \"disabled\": suppress for this batch (same as omitting `webhook`).","isRequired":true,"uniqueKey":"webhook.oneOf.0.mode","typeLabel":"enum\u003cstring>"},"url":{"oneOf":[{"type":"string","title":"Url","description":"Destination URL. Required (HTTPS, public hostname) iff mode is \"direct\".","maxLength":2048,"uniqueKey":"webhook.oneOf.0.url.oneOf.0","typeLabel":"string"},{"type":"null","title":"Url","description":"Destination URL. Required (HTTPS, public hostname) iff mode is \"direct\".","uniqueKey":"webhook.oneOf.0.url.oneOf.1","typeLabel":"null"}],"uniqueKey":"webhook.oneOf.0.url","typeLabel":"string | null"}},"uniqueKey":"webhook.oneOf.0","typeLabel":"WebhookConfig · object"},{"type":"null","description":"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).","uniqueKey":"webhook.oneOf.1","typeLabel":"null"}],"uniqueKey":"webhook","typeLabel":"WebhookConfig · object | null"}},"type":"object","required":["source"],"title":"CreateBatchRequest","uniqueKey":"","typeLabel":"CreateBatchRequest · object"},"examples":{"Example":{"title":"Example","value":{"source":{"file_ids":["\u003cstring>"],"type":"files"},"engine":"\u003cstring>","extract_text":true,"extract_images":true,"ocr":"auto","table_output_format":"markdown","chunking":"none","chunk_size":1000,"metadata":{},"webhook":{"url":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"c99ae058-5b43-43d6-abb0-56c248c2e632":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"type":"string","title":"Id","isRequired":true,"uniqueKey":"id","typeLabel":"string"},"status":{"type":"string","title":"Status","isRequired":true,"uniqueKey":"status","typeLabel":"string"},"counts":{"properties":{"pending":{"type":"integer","title":"Pending","default":0,"uniqueKey":"counts.pending","typeLabel":"integer"},"running":{"type":"integer","title":"Running","default":0,"uniqueKey":"counts.running","typeLabel":"integer"},"succeeded":{"type":"integer","title":"Succeeded","default":0,"uniqueKey":"counts.succeeded","typeLabel":"integer"},"failed":{"type":"integer","title":"Failed","default":0,"uniqueKey":"counts.failed","typeLabel":"integer"},"cancelled":{"type":"integer","title":"Cancelled","default":0,"uniqueKey":"counts.cancelled","typeLabel":"integer"}},"type":"object","title":"BatchCounts","isRequired":true,"uniqueKey":"counts","typeLabel":"BatchCounts · object"},"total_items":{"type":"integer","title":"Total Items","isRequired":true,"uniqueKey":"total_items","typeLabel":"integer"},"engine":{"oneOf":[{"type":"string","title":"Engine","isRequired":true,"uniqueKey":"engine.oneOf.0","typeLabel":"string"},{"type":"null","title":"Engine","isRequired":true,"uniqueKey":"engine.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"engine","typeLabel":"string | null"},"options":{"additionalProperties":true,"type":"object","title":"Options","isRequired":true,"uniqueKey":"options","typeLabel":"Options · object"},"created_at":{"type":"string","title":"Created At","isRequired":true,"uniqueKey":"created_at","typeLabel":"string"},"expires_at":{"type":"string","title":"Expires At","isRequired":true,"uniqueKey":"expires_at","typeLabel":"string"},"object":{"type":"string","title":"Object","default":"batch","uniqueKey":"object","typeLabel":"string"},"metadata":{"oneOf":[{"type":"object","title":"Metadata","additionalProperties":true,"uniqueKey":"metadata.oneOf.0","typeLabel":"Metadata · object"},{"type":"null","title":"Metadata","uniqueKey":"metadata.oneOf.1","typeLabel":"null"}],"uniqueKey":"metadata","typeLabel":"Metadata · object | null"},"started_at":{"oneOf":[{"type":"string","title":"Started At","uniqueKey":"started_at.oneOf.0","typeLabel":"string"},{"type":"null","title":"Started At","uniqueKey":"started_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"started_at","typeLabel":"string | null"},"completed_at":{"oneOf":[{"type":"string","title":"Completed At","uniqueKey":"completed_at.oneOf.0","typeLabel":"string"},{"type":"null","title":"Completed At","uniqueKey":"completed_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"completed_at","typeLabel":"string | null"}},"type":"object","required":["id","status","counts","total_items","engine","options","created_at","expires_at"],"title":"BatchResource","uniqueKey":"","typeLabel":"BatchResource · object"},"examples":{"Example":{"title":"Example","value":{"id":"\u003cstring>","status":"\u003cstring>","counts":{"pending":0,"running":0,"succeeded":0,"failed":0,"cancelled":0},"total_items":123,"engine":"\u003cstring>","options":{},"created_at":"\u003cstring>","expires_at":"\u003cstring>","object":"batch","metadata":{},"started_at":"\u003cstring>","completed_at":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"d9a92c24-b5b8-48e9-bbb9-fa42909cb1ca":{"description":"Quota exceeded.","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"3537d09e-e43a-424f-a987-63d377d5debb":{"description":"One or more `file_id`s don't exist for this account (or their 3-day TTL lapsed).","content":{"application/json":{"example":{"error":"file_not_found","file_ids":["file_abc123"]},"examples":{"Example":{"title":"Example","value":{"error":"file_not_found","file_ids":["file_abc123"]}}},"exampleType":"examples"}},"exampleType":"examples"},"544eff09-c8ee-45e3-b0d0-94207937fb23":{"description":"One or more files have no bytes in storage: the upload never completed or expired. A *finished* upload does not 409.","content":{"application/json":{"example":{"error":"file_not_uploaded","file_ids":["file_abc123"]},"examples":{"Example":{"title":"Example","value":{"error":"file_not_uploaded","file_ids":["file_abc123"]}}},"exampleType":"examples"}},"exampleType":"examples"},"ee48d8ee-f806-438f-85f9-1cbdabdec807":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"oneOf":[{"type":"string","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"detail.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"type":"array","title":"Location","isRequired":true,"uniqueKey":"detail.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"type":"string","title":"Message","isRequired":true,"uniqueKey":"detail.items.[INDEX].msg","typeLabel":"string"},"type":{"type":"string","title":"Error Type","isRequired":true,"uniqueKey":"detail.items.[INDEX].type","typeLabel":"string"},"input":{"oneOf":[{"title":"Input"}],"uniqueKey":"detail.items.[INDEX].input","typeLabel":"any"},"ctx":{"type":"object","title":"Context","uniqueKey":"detail.items.[INDEX].ctx","typeLabel":"Context · object"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","uniqueKey":"detail.items.[INDEX]","typeLabel":"ValidationError · object"},"type":"array","title":"Detail","uniqueKey":"detail","typeLabel":"ValidationError · object[]"}},"type":"object","title":"HTTPValidationError","uniqueKey":"","typeLabel":"HTTPValidationError · object"},"examples":{"Example":{"title":"Example","value":{"detail":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>","input":"\u003cunknown>","ctx":{}}]}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"86843a74-e40d-40e2-aac8-9ef493aacd0c":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-KEY","scopes":[]}}},"servers":{"dd30c128-e109-412d-8b2e-00d772db84e5":{"url":"https://api.hanji.dev","description":"production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"X-API-KEY","scopes":[]},"schema":{"title":"X-API-KEY","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"APIKeyHeader","name":"X-API-KEY"}],"title":"APIKeyHeader"}]},"originalFileLocation":"openapi.json"},"subdomain":"youlearn-b6958d02","siteName":"Hanji","title":"Create a batch - Hanji","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-11T22:42:38.941Z","originalFileLocation":"api-reference/v1/create-a-batch.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=\"light\";if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"light\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Submit uploaded files as one batch job. Returns immediately with status: \u0026quot;pending\u0026quot;; poll GET /v1/batches/{batch_id} for per-item progress. Pass an Idempotency-Key header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Hanji\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create a batch - Hanji\">\u003cmeta data-mint-head property=\"og:description\" content=\"Submit uploaded files as one batch job. Returns immediately with status: \u0026quot;pending\u0026quot;; poll GET /v1/batches/{batch_id} for per-item progress. Pass an Idempotency-Key header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Hanji\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.hanji.dev/api-reference/v1/create-a-batch\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://youlearn-b6958d02.mintlify.site/_mintlify/api/og/v2?division=Async+batch\u0026amp;title=Create+a+batch\u0026amp;description=Submit+uploaded+files+as+one+batch+job.+Returns+immediately+with+%60status%3A+%22pending%22%60%3B+poll+%60GET+%2Fv1%2Fbatches%2F%7Bbatch_id%7D%60+for+per-item+progress.+Pass+an+%60Idempote\u0026amp;theme=4faa1fd56b7cd8c28d323323\u0026amp;signature=e4862a5dc8ba73df2e4a941e5b0325e0eabf30b162741a380d99c883b13f0460\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create a batch - Hanji\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Submit uploaded files as one batch job. Returns immediately with status: \u0026quot;pending\u0026quot;; poll GET /v1/batches/{batch_id} for per-item progress. Pass an Idempotency-Key header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://youlearn-b6958d02.mintlify.site/_mintlify/api/og/v2?division=Async+batch\u0026amp;title=Create+a+batch\u0026amp;description=Submit+uploaded+files+as+one+batch+job.+Returns+immediately+with+%60status%3A+%22pending%22%60%3B+poll+%60GET+%2Fv1%2Fbatches%2F%7Bbatch_id%7D%60+for+per-item+progress.+Pass+an+%60Idempote\u0026amp;theme=4faa1fd56b7cd8c28d323323\u0026amp;signature=e4862a5dc8ba73df2e4a941e5b0325e0eabf30b162741a380d99c883b13f0460\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/youlearn-b6958d02/RkqqEpAEerHVf39r/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Hanji\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0c0c0c\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.hanji.dev/api-reference/v1/create-a-batch\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/v1/create-a-batch.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.hanji.dev/#organization\",\"name\":\"Hanji\",\"url\":\"https://docs.hanji.dev\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/youlearn-b6958d02/Jy2a4ZjGgDJm0OsT/logo/light.svg?fit=max\u0026auto=format\u0026n=Jy2a4ZjGgDJm0OsT\u0026q=85\u0026s=04213e4d86750738bd50b582e537d2f0\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.hanji.dev#website\",\"name\":\"Hanji\",\"url\":\"https://docs.hanji.dev\",\"publisher\":{\"@id\":\"https://docs.hanji.dev/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.hanji.dev/api-reference/v1/create-a-batch#webpage\",\"url\":\"https://docs.hanji.dev/api-reference/v1/create-a-batch\",\"name\":\"Create a batch\",\"description\":\"Submit uploaded files as one batch job. Returns immediately with status: \\\"pending\\\"; poll GET /v1/batches/{batch_id} for per-item progress. Pass an Idempotency-Key header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.\",\"dateModified\":\"2026-08-11T22:42:38.941Z\",\"isPartOf\":{\"@id\":\"https://docs.hanji.dev#website\"},\"breadcrumb\":{\"@id\":\"https://docs.hanji.dev/api-reference/v1/create-a-batch#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.hanji.dev/api-reference/v1/create-a-batch#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Async batch\",\"item\":\"https://docs.hanji.dev/api-reference/v1/register-a-file-for-batch-upload\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create a batch\",\"item\":\"https://docs.hanji.dev/api-reference/v1/create-a-batch\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.hanji.dev/api-reference/v1/create-a-batch#apireference\",\"headline\":\"Create a batch\",\"name\":\"Create a batch\",\"description\":\"Submit uploaded files as one batch job. Returns immediately with status: \\\"pending\\\"; poll GET /v1/batches/{batch_id} for per-item progress. Pass an Idempotency-Key header to make retries safe: the same key within 3 days returns the same batch instead of creating a duplicate.\",\"url\":\"https://docs.hanji.dev/api-reference/v1/create-a-batch\",\"mainEntityOfPage\":{\"@id\":\"https://docs.hanji.dev/api-reference/v1/create-a-batch#webpage\"},\"dateModified\":\"2026-08-11T22:42:38.941Z\",\"publisher\":{\"@id\":\"https://docs.hanji.dev/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.hanji.dev#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Hanji\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Hanji\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/v1/create-a-batch.md","siteName":"Hanji","nav":{"global":null,"pages":[{"title":"Introduction","sidebarTitle":"Introduction","href":"/introduction"},{"group":"Guides","pages":[{"title":"Batch processing","sidebarTitle":"Batch processing","href":"/guides/batch"},{"title":"Schema extraction","sidebarTitle":"Schema extraction","href":"/guides/schema-extraction"},{"title":"Webhooks","sidebarTitle":"Webhooks","href":"/guides/webhooks"}]},{"group":"Parse (sync)","pages":[{"title":"Parse a document by URL","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/parse","href":"/api-reference/v1/parse-a-document-by-url"},{"title":"Parse an uploaded document","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/parse/file","href":"/api-reference/v1/parse-an-uploaded-document"}]},{"group":"Schema extraction","pages":[{"title":"Fill a schema from a document by URL","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/extract/schema","href":"/api-reference/v1/fill-a-schema-from-a-document-by-url"},{"title":"Fill a schema from an uploaded document","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/extract/schema/file","href":"/api-reference/v1/fill-a-schema-from-an-uploaded-document"}]},{"group":"Async batch","pages":[{"title":"Register a file for batch upload","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/files","href":"/api-reference/v1/register-a-file-for-batch-upload"},{"title":"Check upload status","description":"Fetch a file's metadata and upload `status`. Useful to confirm a presigned PUT landed before submitting a batch, though `POST /v1/batches` re-checks S3 on submit, so this call is optional.","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/files/{file_id}","href":"/api-reference/v1/check-upload-status"},{"title":"Create a batch","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/batches","href":"/api-reference/v1/create-a-batch"},{"title":"List your batches","description":"Your account's batches, newest first, with cursor pagination and an optional `status` filter.","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/batches","href":"/api-reference/v1/list-your-batches"},{"title":"Poll a batch","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/batches/{batch_id}","href":"/api-reference/v1/poll-a-batch"},{"title":"Download an item result","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/batches/{batch_id}/items/{item_id}/result","href":"/api-reference/v1/download-an-item-result"},{"title":"Cancel a batch","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/batches/{batch_id}/cancel","href":"/api-reference/v1/cancel-a-batch"},{"title":"batch.update webhook","openapi":"openapi.json webhook batch.update","href":"/api-reference/batch-update-webhook"}]}]},"basePath":"","title":"Create a batch - Hanji","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CiUHMMOm.js","snippetPresets-BgfXU7Bw.js","utils-DWvOwgy_.js","style-to-object-BY3JEAdk.js","utils-BN7RXSMJ.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-CFw8bq89.js","conditional-requirements-CFM0id0Q.js","cloneDeep-CAwdfOU2.js","_Uint8Array-BJr8e-ZL.js","isObject-FP1Yky1u.js","ApiExamples-XX0UgMZK.js","usePlaygroundInputsStore-DXDFSa1V.js","shallow-CdX5aREi.js","isEqual-CoOaxexF.js","CodeSnippets-Cg2wpzWm.js","CodeSnippet-D_HwgQO_.js","getApiPlaygroundDisplay-CmCoerhe.js","Page-CVJ-f_k1.js","DynamicMarkdown-CQM9Bhbv.js","SectionHeading-DpbrP8nQ.js","icon-BPCgijHy.js","MethodPill-GQ8DuY0c.js","getPastedJson-Cb5mT31m.js","Check2Icon-a7bUI6e8.js","axios-CsQoIw0U.js","Markdown-CX2QY19L.js","AssistantPageLink-CY3bFglh.js","dist-Dl6_zDnT.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}