API Request Parameters Reference#

This reference covers the request headers, processing modes, and configuration parameters available across all EnConvert API endpoints — including async_mode, direct_download, callback_url, output_filename, and pdf_options. It explains sync mode (200 OK with the result) versus async mode (202 Accepted with a batch_id), presigned URL responses, and the file size, monthly conversion, and storage limits enforced per plan.

Request Headers#

Endpoint Types#

Enconvert has two types of conversion endpoints, each with a different request format:

URL-Based Endpoints#

Accept a JSON body (application/json) with a url parameter. Support async mode, batch processing, and browser rendering options.

Endpoints: url-to-pdf, url-to-screenshot, website-to-pdf, website-to-screenshot

File Upload Endpoints#

Accept a file via multipart/form-data. Synchronous only. No batch or async support.

Endpoints: All data format, document to PDF, and image conversion endpoints.

Sync vs Async Mode#

• Sync mode is the default. The server processes the conversion and returns the result in the response.
• Async mode is triggered automatically when you submit multiple URLs, or explicitly via async_mode: true. Requires the has_async_mode feature on your subscription plan.
• File upload endpoints are always synchronous. The async_mode parameter does not apply.
• Public keys are restricted to sync mode with a single URL.

Direct Download#

Controls whether the API returns raw file bytes or a JSON response with a presigned download URL.

Default Behavior#

Private Key with direct_download=true#

Returns raw file bytes:

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

Response Headers#

All conversion responses include these metadata headers:

Restrictions#

• direct_download cannot be used with async_mode: true (returns 400)
• direct_download cannot be used with multiple URLs (returns 400)

Output Filename#

Customize the output filename using the output_filename parameter. A UTC timestamp is always appended to ensure uniqueness:

{output_filename}_{YYYYMMDD_HHMMSSmmm}.{ext}

Default naming: - File uploads: Derived from the input filename (e.g., report.docx becomes report_20260405_123456789.pdf) - URL conversions: Derived from the domain name (e.g., example_20260405_123456789.pdf) - Fallback: output_20260405_123456789.{ext}

If you include the target extension in your custom name, it is stripped before the timestamp is appended to avoid duplication.

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

Produces: my-report_20260405_123456789.pdf

PDF Options#

Endpoints that produce PDF output support an optional pdf_options parameter for controlling page layout, headers, footers, and color mode.

Supported Endpoints#

Fields#

Supported page sizes: A0, A1, A2, A3, A4, A5, A6, B0, B1, B2, B3, B4, B5, Letter, Legal, Tabloid, Ledger

Header/footer template variables: {{page}}, {{total_pages}}, {{date}}, {{title}}, {{url}}

Passing pdf_options#

URL-based endpoints -- JSON object in the request body:

{
    "url": "https://example.com",
    "pdf_options": {
        "page_size": "Letter",
        "orientation": "landscape",
        "margins": {"top": 20, "bottom": 20, "left": 15, "right": 15},
        "footer": {
            "content": "Page {{page}} of {{total_pages}}",
            "height": 10
        }
    }
}

File upload endpoints -- JSON string in a form field:

curl -X POST https://api.enconvert.com/v1/convert/html-to-pdf \
  -H "X-API-Key: sk_live_your_private_key" \
  -F "[email protected]" \
  -F 'pdf_options={"page_size": "Letter", "grayscale": true}'

Image Options (Image Endpoints Only)#

The SVG rasterization endpoints (svg-to-png, svg-to-jpeg, svg-to-webp) accept optional output dimensions:

Passing both dimensions sets the exact canvas size, which may change the aspect ratio. Requests above 25,000,000 total output pixels return 400.

The compress-image endpoint accepts a size budget:

Browser & Rendering Options (URL Endpoints Only)#

These parameters control how the browser renders the page before conversion. They apply to url-to-pdf, url-to-screenshot, website-to-pdf, and website-to-screenshot.

Authentication & Custom Requests (URL Endpoints Only)#

These parameters allow converting pages behind authentication or requiring specific cookies/headers. They require a plan with basic auth access (Starter+).

URL Validation (SSRF Protection)#

The url on every URL-based endpoint must be a public http:// or https:// address. Before the browser fetches anything, the URL is screened and rejected with 400 Bad Request when it:

• uses a scheme other than http/https;
• embeds credentials (https://user:pass@host/ — use the auth field instead);
• targets localhost, a cloud metadata hostname, or an IP that resolves into a private, loopback, link-local, reserved, or otherwise non-public range;
• uses a non-standard IP notation (octal, hexadecimal, or packed-integer) that could resolve ambiguously.

This applies to the seed URL, to every URL in a batch, and to the pages discovered by the website-to-* crawl endpoints.

Non-HTML URLs#

When a URL returns non-HTML content, the response depends on the endpoint:

• url-to-markdown returns the raw body inside a fenced code block (with a json or text language hint) for application/json and text/plain responses, instead of running article extraction over the browser's viewer.
• url-to-pdf and url-to-screenshot return 415 Unsupported Media Type for application/json responses (a browser JSON viewer makes a poor PDF/image). Use url-to-markdown to capture JSON. Plain text renders normally.

Presigned URLs#

When direct_download is false (or for public key responses), the API returns a presigned URL for downloading the converted file directly from storage.

• Expiry: Presigned URLs expire after 15 minutes. Download the file promptly after receiving the URL.
• Reusable: URLs can be used multiple times before they expire.
• Fresh on poll: The batch status endpoint generates fresh presigned URLs on each request.

File Size Limits#

Maximum upload file size depends on your subscription plan:

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

{
    "error": "File too large",
    "file_size": 10485760,
    "max_size": 5242880,
    "tier": "free",
    "key_type": "private"
}

File size is validated via the Content-Length request header before the file body is read.

Monthly Conversion Limits#

Each plan has a monthly cap on total conversions:

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

{
    "detail": "Monthly conversion limit reached (100/100). Upgrade your plan to continue."
}

For batch requests, the entire batch count is pre-checked against the remaining quota before any processing begins. If 10 URLs are submitted but only 3 conversions remain, the entire batch is rejected upfront.

Storage Limits#

Projects on plans with storage allocations are subject to storage usage limits. When the project's accumulated file storage reaches the plan's limit, conversions are blocked:

{
    "detail": "Storage limit reached. Delete files or upgrade your storage plan to continue."
}

Feature Gating Summary#

Certain features are restricted to specific subscription tiers:

When a gated feature is used on an unsupported plan, the API returns 403 Forbidden with a message indicating which feature requires a plan upgrade.

Frequently asked questions#

What is the difference between sync and async mode in the EnConvert API?#

Sync mode is the default: the server processes the conversion and returns 200 OK with the result. Async mode returns 202 Accepted with a batch_id and is triggered automatically by multiple URLs or explicitly via async_mode: true. Async requires a private key and the has_async_mode plan feature (Starter and above).

What does the direct_download parameter do?#

It controls whether the API returns raw file bytes (true) or a JSON response with a presigned download URL (false). It cannot be combined with async_mode: true or multiple URLs — both return 400. For public and dashboard keys it is forced to true, but the response is still JSON with a presigned_url.

How long do presigned download URLs stay valid?#

Presigned URLs expire after 15 minutes and can be used multiple times before expiry. The batch status endpoint generates fresh presigned URLs on each request, so re-polling always returns working links.

How do I set a custom output filename for a conversion?#

Pass the output_filename parameter. A UTC timestamp is always appended for uniqueness, producing {output_filename}_{YYYYMMDD_HHMMSSmmm}.{ext}, and a target extension included in your custom name is stripped to avoid duplication.

Why does the API return 403 Forbidden when I set async_mode to true?#

Async mode is not available on the free plan. Setting async_mode: true or submitting multiple URLs on a plan without async access returns 403 Forbidden with a message indicating which feature requires a plan upgrade.