URL Converters

URL converters accept one or more URLs in a JSON request body and convert the target web pages to PDF or screenshot (PNG) format. These endpoints support single-URL synchronous conversion, batch processing, and asynchronous execution.

Available Endpoints

Request Format

URL converters accept application/json request bodies.

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

Parameters

Single URL -- Synchronous

The simplest usage: convert a single URL and receive the result immediately.

Request

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "output_filename": "example-page.pdf"
  }'

Response (Private Key)

HTTP 200 OK

{
  "success": true,
  "message": "Conversion successful",
  "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/example-page.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
  "object_key": "live/files/abc123/url-to-pdf/example-page.pdf",
  "filename": "example-page.pdf",
  "file_size": 184320,
  "conversion_time": 3.721
}

Direct Download Mode

When direct_download is set to true, the API returns the converted file as a binary stream instead of a JSON response. This is useful for embedding conversion directly into download flows.

Request

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

Response

HTTP 200 OK -- Binary file stream

The response body contains the raw file content. Metadata is provided in the response headers:

Clear Capture Mode

Enconvert uses an intelligent page preparation system called Clear Capture Mode to ensure high-fidelity conversions. This system automatically handles the many challenges of converting live web pages into static documents.

All Clear Capture features are enabled by default. You can selectively disable them using the boolean parameters listed in the Parameters table above.

Cookie Banner Dismissal

When handle_cookies is enabled, the converter automatically detects and dismisses cookie consent banners, GDPR overlays, and similar pop-ups. It recognizes common consent management platforms and clicks the appropriate "Accept" or "Close" buttons so they do not appear in the output.

Sticky Header Handling

When handle_sticky_header is enabled, the converter detects elements with position: fixed or position: sticky (such as navigation bars) and neutralizes them. This prevents sticky headers from being rendered at the top of every page in the PDF output.

Lazy-Load Triggering

When enable_scroll is enabled, the converter scrolls through the full length of the page to trigger lazy-loaded content. This ensures that elements which only load on scroll (images, sections, infinite scroll content) are fully rendered before capture.

Image Loading

When wait_for_images is enabled, the converter waits for all <img> elements and CSS background images to finish loading before performing the capture. Combined with load_media, this ensures no broken image placeholders appear in the output.

Animation Handling

The converter detects and triggers common animation libraries to ensure all animated content is in its final rendered state:

• AOS (Animate on Scroll) -- all elements are revealed
• WOW.js -- all animated elements are displayed
• ScrollReveal -- all scroll-triggered reveals are completed
• GSAP (GreenSock) -- timeline animations are advanced to their end state
• Swiper -- slider/carousel elements are properly rendered

Modal and Popup Closing

The converter automatically detects and closes modal dialogs, pop-up overlays, and interstitial screens that may obstruct the page content.

Viewport Unit Normalization

CSS viewport units (vh, svh, lvh, dvh) are normalized to match the configured viewport_height. This prevents layout issues where elements sized with viewport units render incorrectly in the headless browser environment.

Elementor Fixes

For pages built with the Elementor page builder, the converter applies targeted fixes to ensure sections, columns, and widgets render at full fidelity. This includes correcting known rendering quirks specific to Elementor's CSS framework.

Dropdown Navigation Cleanup

Open dropdown navigation menus are detected and closed before capture, ensuring they do not obscure page content in the final output.

Video Dimension Preservation

Embedded videos (<video>, <iframe> embeds for YouTube, Vimeo, etc.) have their dimensions preserved and are rendered as static placeholder frames so the layout remains intact.

Authenticated Pages

Convert pages that require login or HTTP authentication by providing credentials, session cookies, or custom headers in your request.

HTTP Basic Auth

If the target page is protected by HTTP Basic Authentication (the browser shows a username/password dialog), provide the auth parameter:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://staging.example.com/internal-report",
    "auth": {
      "username": "admin",
      "password": "s3cret"
    }
  }'

The browser automatically responds to the server's 401 challenge with the provided credentials. This works for any site that uses standard HTTP Basic or Digest authentication.

Session Cookies

To convert a page that requires an active login session, inject session cookies before the page loads. This is useful when you have an existing authenticated session and need to capture a logged-in view.

curl -X POST https://api.enconvert.com/v1/convert/url-to-screenshot \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123def456",
        "domain": ".example.com"
      },
      {
        "name": "user_prefs",
        "value": "theme=dark",
        "domain": ".example.com",
        "path": "/",
        "secure": true,
        "httpOnly": true,
        "sameSite": "Lax"
      }
    ]
  }'

Each cookie object supports the following fields:

*Either domain or url must be provided for each cookie. Maximum 50 cookies per request.

Custom Headers

Send custom HTTP headers with every request made during the page load. This is useful for Bearer token authentication, API keys, or any custom header the target site requires.

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/report",
    "headers": {
      "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
      "X-Tenant-ID": "acme-corp"
    }
  }'

Security

• Credentials are never logged or stored. They are used only for the duration of the conversion request and discarded immediately.
• The browser context is created fresh for each request and destroyed after conversion — cookies and credentials do not persist between requests.
• Maximum 50 cookies and 20 custom headers per request.

PDF Options

Control the PDF output format by including a pdf_options object in your request. All fields are optional — omit pdf_options entirely to use default behavior.

Parameters

Template Variables

Use these placeholders in header.content and footer.content. They are automatically replaced with the actual values at render time.

Single-Page Behavior

When single_page is true, the following pdf_options fields are silently ignored because a single continuous page has no page breaks:

• scale — content is captured at natural scale to preserve full-page fidelity
• header — no repeating pages for the header to appear on
• footer — no repeating pages for the footer to appear on
• orientation — the page is always a single tall strip

The following fields still apply:

• page_size — determines the page width (height is calculated from content)
• margins — applied to the content area
• grayscale — applied as a post-processing step

Examples

Landscape A3 with custom margins:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report",
    "single_page": false,
    "pdf_options": {
      "page_size": "A3",
      "orientation": "landscape",
      "margins": { "top": 20, "bottom": 20, "left": 15, "right": 15 }
    }
  }'

Grayscale PDF with page numbers:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "single_page": false,
    "pdf_options": {
      "grayscale": true,
      "footer": {
        "content": "<div style=\"font-size: 10px; width: 100%; text-align: center;\">Page {{page}} of {{total_pages}}</div>",
        "height": 15
      }
    }
  }'

Zoomed-out rendering (fit wide content):

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/wide-dashboard",
    "single_page": false,
    "pdf_options": {
      "page_size": "A4",
      "orientation": "landscape",
      "scale": 0.6
    }
  }'

Custom page dimensions (invoice receipt):

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/receipt/12345",
    "single_page": false,
    "pdf_options": {
      "page_width": 80,
      "page_height": 200,
      "margins": { "top": 5, "bottom": 5, "left": 5, "right": 5 }
    }
  }'

Error Responses

Invalid URL (400)

{
  "success": false,
  "error": "Invalid URL provided",
  "code": "INVALID_URL"
}

Direct Download Conflict (400)

{
  "success": false,
  "error": "direct_download cannot be used with async_mode or multiple URLs",
  "code": "INVALID_PARAMETERS"
}