Convert Source

Convert a single document from a remote URL (HTTP/HTTPS) into AI-ready formats. To convert more than one document, see Convert Batch.

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	An array containing the single source object to convert
`options`	object	No	Conversion options (see Options)

Source Object

The 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

The options object supports the following parameters:

Parameter	Type	Default	Description
`to_formats`	array	`["md"]`	Output formats, any of: `"md"`, `"html"`, `"json"`, `"text"`, `"doclang"`

By default, /v1/result/{task_id} returns result artifacts for the converted document, including a download URL for each output artifact.

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
}

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)
`failure`	object	Failure details if the task failed, otherwise null
`error_message`	string	Error description if status is `"failure"`

Error Responses

See Error Handling for the full error model. The responses most specific to source conversion:

Status	Description
`400`	Bad request — malformed request
`401`	Unauthorized — missing or invalid API key
`422`	Validation error — invalid URL syntax or unsupported target
`429`	Too many requests — rate limit exceeded
`500`	Internal server error
`502`	Gateway or upstream error

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 conversion result artifacts

Rate Limits

See Rate Limits for the default limits and 429 handling.

Best Practices

Use appropriate output formats - Choose markdown for RAG applications, json for structured data extraction
Convert collections with the batch endpoint - For more than one document, use Convert Batch
Handle errors gracefully - Always check the task_status and error_message fields
Implement retry logic - Use exponential backoff for transient failures

Common Errors

Invalid URL syntax — requests with malformed URLs are rejected with 422. Use a valid http:// or https:// URL.

Unreachable URL — the request can be accepted as an async task. When the source cannot be retrieved, the result reports it as a document-level failure with num_failed > 0.

Unsupported target — if you provide a target override, unsupported target values are rejected with 422.

Unsupported format — the request can be accepted as an async task and reported as a document-level failure in /v1/result/{task_id}. Check num_failed and document statuses. See the FAQ for supported formats.

Convert File - Upload and convert a local file
Convert Batch - Convert multiple documents, including from cloud storage
Poll Status - Check conversion progress
Get Results - Retrieve conversion result artifacts

Convert Source

On this page