Parameters & Options

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

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 "file=@report.html" \
  -F 'pdf_options={"page_size": "Letter", "grayscale": true}'

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+).

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.