Convert Source

Convert documents from remote URLs (HTTP/HTTPS) into AI-ready formats.

Endpoint

POST /v1/convert/source/async

Request Headers

Header	Required	Description
`X-Api-Key`	Yes	Your API key for authentication
`Content-Type`	Yes	Must be `application/json`

Request Body

The request body must be a JSON object with the following structure:

Parameter	Type	Required	Description
`sources`	array	Yes	Array of source objects to convert
`options`	object	Conditional	Conversion options (see Options)

Source Object

Each source object in the sources array must contain:

Parameter	Type	Required	Description
`kind`	string	Yes	Must be `"http"` for URL sources
`url`	string	Yes	The URL of the document to convert

Options

options is required if you are uploading multiple documents. The options object supports 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"`, `"processing"`, `"success"`, or `"failure"`
`task_position`	integer	Position in queue (null when processing or complete)
`task_meta`	object	Additional metadata (currently unused)
`error_message`	string	Error description if status is `"failure"`

Error Responses

To be added.

Examples

Find examples of using the Source 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

Rate Limits

To be added.

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 - Process multiple documents together for efficiency
Handle errors gracefully - Always check the task_status and error_message fields
Implement retry logic - Use exponential backoff for transient failures

Common Errors

To be added.

Convert File - Upload and convert local files
Poll Status - Check conversion progress
Get Results - Retrieve converted documents

Convert Source

On this page