Convert File

Use this endpoint to upload and convert local documents into different formats. To upload a PDF from a URL, see Convert Source.

Endpoint

POST {SERVICE_URL}/v1/convert/file/async

Request Headers

Header	Required	Description
`X-Api-Key`	Yes	Your API key for authentication
`Content-Type`	Yes	Must be `multipart/form-data`

Request Body

The request must be sent as multipart/form-data with the following fields:

Parameter	Type	Required	Description
`files`	file	Yes	The file(s) to upload and convert (use `@` prefix for file paths)
`options`	JSON string	Conditional	Conversion options as a JSON string (see Options)

Options

options is required if you are uploading multiple documents. When provided, the options parameter must be a JSON string containing an object with the following parameters:

Parameter	Type	Default	Description
`output_format`	string	`"json"`	Output format: `"json"`, `"markdown"`, or `"html"`

Response

Success Response (20X Accepted)

Returns a task object that can be used to poll for completion:

{
  "task_id": "{TASK_ID}",
  "task_type": "convert",
  "task_status": "pending",
  "task_position": 1,
  "task_meta": null,
  "error_message": null
}

Field	Type	Description
`task_id`	string	Unique identifier for this conversion task (generated by the service)
`task_type`	string	Always `"convert"` for conversion tasks
`task_status`	string	Current status: `"pending"`, `"success"`, or `"failure"`
`task_position`	integer	Position in queue (null when processing or complete)
`task_meta`	object	Additional metadata
`error_message`	string	Error description if status is `"failure"`

Error Responses

To be added.

Examples

Find examples of using the File Conversion endpoint in the Examples section.

Next Steps

After submitting a conversion request:

Poll for status - Use the /v1/status/poll/{task_id} endpoint to check conversion progress
Retrieve results - Once status is "success", use the /v1/result/{task_id} endpoint to get the converted document

Best Practices

Use appropriate output formats - Choose markdown for RAG applications, json for structured data extraction
Enable low-latency mode - For real-time applications where speed is critical
Batch similar documents - Upload multiple files together for efficiency
Handle errors gracefully - Always check the task_status and error_message fields
Implement retry logic - Use exponential backoff for transient failures
Validate files locally - Check file format and size before uploading to avoid errors

Common Errors

To be added.

File Format Support

The Convert File endpoint supports the same formats as Convert Source:

PDF documents - Including scanned PDFs with OCR
Images - PNG, JPEG, TIFF, BMP, GIF
Microsoft Office - DOCX, PPTX, XLSX
HTML - Web pages and HTML documents
Markdown - MD files
Text files - TXT, CSV

For the most up-to-date list, see the FAQ.

Convert Source - Convert documents from URLs
Poll Status - Check conversion progress
Get Results - Retrieve converted documents

Convert File

On this page