{"openapi":"3.1.0","info":{"title":"VNConvert OCR API","description":"Asynchronous OCR API for scanned PDFs and images to editable Word DOCX and Excel XLSX, with page selection and multi-language OCR.","version":"2.0"},"paths":{"/v2/health":{"get":{"tags":["OCR API V2"],"summary":"OCR API health","operationId":"health_v2_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v2/jobs":{"post":{"tags":["OCR API V2"],"summary":"Create OCR job from URL","operationId":"create_job_v2_jobs_post","responses":{"200":{"description":"Idempotent replay of an existing job","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"job":{"type":"object","properties":{"job_id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","waiting_resource","processing","completed","failed","timeout"]},"input":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"sha256":{"type":"string","nullable":true},"total_pages":{"type":"integer","nullable":true}}},"output":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"format":{"type":"string","enum":["docx","xlsx"]},"sha256":{"type":"string","nullable":true}}},"params":{"type":"object","properties":{"pages":{"type":"string"},"selected_pages_count":{"type":"integer","nullable":true},"lang":{"type":"string"}}},"created_at":{"type":"string","nullable":true},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"poll_after_seconds":{"type":"integer"},"result":{"type":"object","properties":{"available":{"type":"boolean"},"endpoint":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true}}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}},"idempotent_replay":{"type":"boolean"}}}}}},"201":{"description":"OCR job created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"job":{"type":"object","properties":{"job_id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","waiting_resource","processing","completed","failed","timeout"]},"input":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"sha256":{"type":"string","nullable":true},"total_pages":{"type":"integer","nullable":true}}},"output":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"format":{"type":"string","enum":["docx","xlsx"]},"sha256":{"type":"string","nullable":true}}},"params":{"type":"object","properties":{"pages":{"type":"string"},"selected_pages_count":{"type":"integer","nullable":true},"lang":{"type":"string"}}},"created_at":{"type":"string","nullable":true},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"poll_after_seconds":{"type":"integer"},"result":{"type":"object","properties":{"available":{"type":"boolean"},"endpoint":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true}}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}},"idempotent_replay":{"type":"boolean"}}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200},"description":"Unique key for one logical create request. Safe retries return the existing job."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"client_file_id":{"type":"string","example":"client-file-001"},"input":{"type":"object","required":["type","format","url"],"properties":{"type":{"type":"string","enum":["url"],"default":"url"},"format":{"type":"string","enum":["pdf","png","jpg","jpeg","bmp"]},"url":{"type":"string","format":"uri"}}},"output":{"type":"object","properties":{"format":{"type":"string","enum":["docx","xlsx"],"default":"docx","example":"docx"}}},"params":{"type":"object","properties":{"pages":{"type":"string","default":"all","example":"1"},"lang":{"type":"string","enum":["auto","zh-Hans","zh-Hant","cs","nl","en","fr","de","el","id","it","ja","ko","pl","pt","ru","es","th","tr","uk","vi"],"default":"auto","example":"auto"}}}}}}}}},"get":{"tags":["OCR API V2"],"summary":"List jobs for the authenticated client","operationId":"list_jobs_v2_jobs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/jobs/upload":{"post":{"tags":["OCR API V2"],"summary":"Create OCR job from direct upload","operationId":"create_upload_job_v2_jobs_upload_post","responses":{"200":{"description":"Idempotent replay of an existing job","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"job":{"type":"object","properties":{"job_id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","waiting_resource","processing","completed","failed","timeout"]},"input":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"sha256":{"type":"string","nullable":true},"total_pages":{"type":"integer","nullable":true}}},"output":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"format":{"type":"string","enum":["docx","xlsx"]},"sha256":{"type":"string","nullable":true}}},"params":{"type":"object","properties":{"pages":{"type":"string"},"selected_pages_count":{"type":"integer","nullable":true},"lang":{"type":"string"}}},"created_at":{"type":"string","nullable":true},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"poll_after_seconds":{"type":"integer"},"result":{"type":"object","properties":{"available":{"type":"boolean"},"endpoint":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true}}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}},"idempotent_replay":{"type":"boolean"}}}}}},"201":{"description":"OCR job created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"job":{"type":"object","properties":{"job_id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","waiting_resource","processing","completed","failed","timeout"]},"input":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"sha256":{"type":"string","nullable":true},"total_pages":{"type":"integer","nullable":true}}},"output":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"format":{"type":"string","enum":["docx","xlsx"]},"sha256":{"type":"string","nullable":true}}},"params":{"type":"object","properties":{"pages":{"type":"string"},"selected_pages_count":{"type":"integer","nullable":true},"lang":{"type":"string"}}},"created_at":{"type":"string","nullable":true},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"poll_after_seconds":{"type":"integer"},"result":{"type":"object","properties":{"available":{"type":"boolean"},"endpoint":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true}}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}},"idempotent_replay":{"type":"boolean"}}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200},"description":"Unique key for one logical create request. Safe retries return the existing job."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"output_format":{"type":"string","enum":["docx","xlsx"],"default":"docx","example":"docx"},"pages":{"type":"string","default":"all","example":"1"},"lang":{"type":"string","enum":["auto","zh-Hans","zh-Hant","cs","nl","en","fr","de","el","id","it","ja","ko","pl","pt","ru","es","th","tr","uk","vi"],"default":"auto","example":"auto"},"client_file_id":{"type":"string","example":"client-file-001"}}}}}}}},"/v2/jobs/{job_id}":{"get":{"tags":["OCR API V2"],"summary":"Get OCR job status","operationId":"get_job_v2_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Current public job state","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"job":{"type":"object","properties":{"job_id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","waiting_resource","processing","completed","failed","timeout"]},"input":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"sha256":{"type":"string","nullable":true},"total_pages":{"type":"integer","nullable":true}}},"output":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true},"format":{"type":"string","enum":["docx","xlsx"]},"sha256":{"type":"string","nullable":true}}},"params":{"type":"object","properties":{"pages":{"type":"string"},"selected_pages_count":{"type":"integer","nullable":true},"lang":{"type":"string"}}},"created_at":{"type":"string","nullable":true},"started_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"poll_after_seconds":{"type":"integer"},"result":{"type":"object","properties":{"available":{"type":"boolean"},"endpoint":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"size_bytes":{"type":"integer","nullable":true}}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}},"idempotent_replay":{"type":"boolean"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/jobs/{job_id}/result":{"get":{"tags":["OCR API V2"],"summary":"Download OCR result","operationId":"get_result_v2_jobs__job_id__result_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"DOCX or XLSX result file","content":{"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}