Convert File

Use this endpoint to upload and convert up to 3 local files into different formats. To convert a document from a URL, see Convert Source; to convert larger collections or ingest from cloud storage, see Convert Batch.

Endpoint

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

Request Headers

Request Body

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

Options

When provided, the options parameter must be a JSON string containing an object with the following parameters:

Response

Success Response (200 OK)

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,
  "failure": null,
  "error_message": null
}

Error Responses

See Error Handling for the full error model. The responses most specific to file upload:

Examples

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

Next Steps

After submitting a conversion request:

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

Best Practices

1. Use appropriate output formats - Choose markdown for RAG applications, json for structured data extraction
2. Convert collections with the batch endpoint - For more than 3 files, or to ingest from cloud storage, use Convert Batch
3. Handle errors gracefully - Always check the task_status and error_message fields
4. Implement retry logic - Use exponential backoff for transient failures
5. Validate files locally - Check file format and size before uploading to avoid errors

Common Errors

No file provided — include at least one file with the -F flag (files=@/path/to/file) in curl, or set the file field correctly in your HTTP client. Requests without input should be rejected during request validation.

Unsupported file format — the task can complete with task_status: "success" while the result has num_failed > 0 and a document-level failure status. Check result counters and each document's status. See the FAQ for supported formats.

Invalid options JSON — the options field must contain valid JSON. In bash, wrap it in single quotes: -F 'options={"to_formats":["html"]}'

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.

Rate Limits

See Rate Limits for the default limits and 429 handling.

Related Endpoints

• Convert Source - Convert a document from a URL
• Convert Batch - Convert multiple documents, including from cloud storage
• Poll Status - Check conversion progress
• Get Results - Retrieve conversion result artifacts