Parameters & Options

This page covers the request headers, processing modes, and configuration options available across all Enconvert API endpoints.

Request Headers

Header	Type	Description
X-API-Key	string	Your API key (`sk_...` or `pk_...`). Use this OR the Authorization header.
Authorization	string	Bearer token from `/v1/auth/token`. Use this OR the X-API-Key header.
Content-Type	string	`application/json` for URL-based converters, `multipart/form-data` for file uploads.
X-Parent-Origin	string	Required for public key token exchange. The parent domain of the widget.

Sync vs Async Mode

The API supports two processing modes. The mode is determined automatically based on your request, or you can explicitly set it using the async_mode parameter.

	Sync Mode (Default)	Async Mode
Trigger	Single URL, `async_mode: false`	Multiple URLs, or `async_mode: true`
Response	`200 OK` with result	`202 Accepted` with `batch_id`
Result	File URL or direct download	Processed in background
Key types	Private & Public	Private only

Sync mode is the default. The server processes the conversion immediately and returns the result in the response body.
Async mode is triggered automatically when you submit multiple URLs in a single request, or when you explicitly set async_mode: true. The server returns a batch_id that you can use to poll for results.

Direct Download

When you include direct_download: true in your request, the API returns the converted file as binary data directly in the response body instead of a JSON payload with a presigned URL. The file is still stored in cloud storage regardless of this setting.

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "direct_download": true}' \
  --output output.pdf

The response includes the following headers with file metadata:

Header	Description
Content-Disposition	Attachment filename (e.g., `attachment; filename="example_20250202_120530123.pdf"`)
X-Object-Key	Storage path of the converted file
X-File-Size	Size of the converted file in bytes
X-Conversion-Time	Time taken for conversion in seconds
X-Filename	Generated filename of the converted file

Output Filename

You can optionally specify a custom output filename using the output_filename parameter. A timestamp is always appended to ensure uniqueness:

{filename}_{YYYYMMDD_HHMMSSmmm}.{ext}

Default behavior: If output_filename is not provided, the filename is derived from the source filename (for file uploads) or the domain name (for URL conversions).
Validation: The filename must match the pattern [a-zA-Z0-9._-]+. Special characters outside this set are not allowed.

{
  "url": "https://example.com",
  "output_filename": "my-report"
}

This produces a file named something like my-report_20250202_120530123.pdf.

File Size Limits

Maximum upload file size depends on your subscription tier:

Free	Basic	Pro
5 MB	50 MB	500 MB

If a file exceeds your tier's size limit, the API returns a 413 Payload Too Large response:

{
  "detail": "File too large. Maximum allowed size for your tier is 5 MB."
}

Upgrade your plan to increase the file size limit.

Monthly Conversion Limits

Each tier has a monthly cap on the total number of conversions:

Tier	Monthly Limit
Free	20 conversions per month
Basic	Unlimited
Pro	Unlimited

When the monthly limit is exceeded, the API returns a 402 Payment Required response:

{
  "detail": "Monthly conversion limit reached. Please upgrade your plan."
}

Monthly limits reset on the 1st of each month. Upgrade to Basic or Pro for unlimited conversions.

← Job Notifications Web Widgets →

API Documentation