Website to PDF API#

The POST /v1/convert/website-to-pdf endpoint crawls an entire website (via sitemap parsing or a full breadth-first crawl), converts each discovered page to a high-fidelity PDF, and bundles the results into a single ZIP archive. Jobs always run asynchronously: the API returns HTTP 202 with a batch_id immediately, completion is signalled via batch status polling, a webhook callback, or an email notification, and the batch status response includes a presigned download URL for the finished ZIP. Requires a paid plan and a private API key.

Endpoint#

POST /v1/convert/website-to-pdf

Content-Type: application/json

Output format: ZIP archive containing one PDF per discovered page.

Mode: Always asynchronous. Returns HTTP 202 immediately.

Authentication#

This endpoint requires a private API key. Public keys are not supported for website capture.

X-API-Key: sk_your_private_key

Request Parameters#

Website Discovery Parameters#

Notification Parameters#

Browser & Rendering Parameters#

These settings apply to the conversion of each individual page within the website.

Authentication & Custom Requests#

PDF Options#

Pass these inside a pdf_options object. They apply to every page in the website.

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

Crawl Modes#

"auto" (default)#

Uses the highest crawl mode your plan allows. If your plan supports full crawling, it runs a full crawl. If your plan supports sitemap-only, it runs sitemap discovery.

"sitemap"#

Discovers pages by parsing the website's sitemap.xml:

1. Fetches {base_url}/sitemap.xml (30-second timeout)
2. If the root element is <sitemapindex>, recursively fetches each child sitemap
3. Extracts all <url><loc> entries from <urlset> elements
4. Returns the full list of discovered URLs

Returns an error if the sitemap is missing, returns a non-200 status, contains invalid XML, or has no URLs.

"full"#

Performs a comprehensive two-phase crawl:

Phase 1 -- Seed discovery:

1. Parses robots.txt for sitemap directives and crawl rules
2. Checks standard sitemap paths (/sitemap.xml, /wp-sitemap.xml, /sitemap_index.xml, etc.)
3. Discovers RSS/Atom feeds from <link> tags and common feed paths
4. Extracts seed URLs from all discovered sources

Phase 2 -- Breadth-first link crawl:

1. Starts from the base URL plus all seed URLs
2. Visits each page and enqueues same-domain links
3. Applies include_patterns and exclude_patterns to filter links
4. Respects robots.txt rules
5. Detects and avoids infinite URL traps (calendar pages, faceted filters, etc.)
6. Deduplicates URLs by normalizing scheme, host, query parameters, and stripping tracking parameters (utm_*, fbclid, gclid, etc.)

Default exclude patterns (when exclude_patterns is not provided):

• Static assets: *.pdf, *.zip, *.jpg, *.png, *.gif, *.svg, *.css, *.js, *.xml, *.json, *.mp4, *.webm, *.woff, *.woff2
• Protected paths: /login, /admin, /cart, /checkout
• Deep pagination: URLs with page= parameters exceeding 3 digits

Response#

202 Accepted (immediate)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 42,
    "total_discovered": 42,
    "discovery_method": "sitemap",
    "output_format": "zip"
}

Batch Status Polling#

Poll with the batch_id from the 202 response:

GET /v1/convert/batch/{batch_id}
X-API-Key: sk_your_private_key

Returns aggregate status, per-URL statuses, and a presigned download URL for the ZIP when complete. See Batch Status Polling for the full response schema.

Webhook Callback Payload#

When callback_url is provided, EnConvert sends a POST request on completion:

{
    "job_id": "batch-uuid",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/website_20260405_123456789.zip",
    "filename": "website_20260405_123456789.zip",
    "file_size": 12345678,
    "total_tasks": 42,
    "successful_tasks": 40,
    "failed_tasks": 2,
    "tasks": [
        {"url": "https://example.com/", "status": "success", "filename": "example_20260405_001.pdf"},
        {"url": "https://example.com/about", "status": "success", "filename": "example_20260405_002.pdf"},
        {"url": "https://example.com/broken", "status": "failed", "error": "Timeout"}
    ]
}

Email Notification#

A completion email is sent to notification_email (or the project owner's email by default) when the job finishes, regardless of success or failure.

Subscription Plan Gating#

Code Examples#

Python (Private Key)#

import requests
import time

# Start the website capture
response = requests.post(
    "https://api.enconvert.com/v1/convert/website-to-pdf",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com",
        "crawl_mode": "sitemap",
        "output_filename": "example-website",
        "pdf_options": {
            "page_size": "A4",
            "orientation": "portrait"
        }
    }
)

data = response.json()
print(f"Batch ID: {data['batch_id']}")
print(f"Pages found: {data['url_count']}")

# Poll for completion
batch_id = data["batch_id"]
while True:
    status = requests.get(
        f"https://api.enconvert.com/v1/convert/batch/{batch_id}",
        headers={"X-API-Key": "sk_your_private_key"}
    ).json()

    print(f"Status: {status['status']} ({status['completed']}/{status['total']})")

    if status["status"] in ("completed", "partial", "failed"):
        if status.get("zip_download_url"):
            print(f"Download: {status['zip_download_url']}")
        break

    time.sleep(5)

PHP (Private Key)#

$ch = curl_init("https://api.enconvert.com/v1/convert/website-to-pdf");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-Key: sk_your_private_key"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://example.com",
        "crawl_mode" => "sitemap",
        "output_filename" => "example-website",
        "pdf_options" => [
            "page_size" => "A4",
            "orientation" => "portrait"
        ]
    ])
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Batch ID: " . $response["batch_id"] . "\n";
echo "Pages found: " . $response["url_count"] . "\n";

Node.js (Private Key)#

const response = await fetch("https://api.enconvert.com/v1/convert/website-to-pdf", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com",
        crawl_mode: "sitemap",
        output_filename: "example-website",
        pdf_options: {
            page_size: "A4",
            orientation: "portrait"
        }
    })
});

const data = await response.json();
console.log(`Batch ID: ${data.batch_id}`);
console.log(`Pages found: ${data.url_count}`);

// Poll for completion
const poll = async () => {
    const status = await fetch(
        `https://api.enconvert.com/v1/convert/batch/${data.batch_id}`,
        { headers: { "X-API-Key": "sk_your_private_key" } }
    ).then(r => r.json());

    console.log(`Status: ${status.status} (${status.completed}/${status.total})`);

    if (["completed", "partial", "failed"].includes(status.status)) {
        if (status.zip_download_url) console.log(`Download: ${status.zip_download_url}`);
        return;
    }
    setTimeout(poll, 5000);
};
poll();

Go (Private Key)#

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "url":             "https://example.com",
        "crawl_mode":      "sitemap",
        "output_filename": "example-website",
        "pdf_options": map[string]interface{}{
            "page_size":   "A4",
            "orientation": "portrait",
        },
    })

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/website-to-pdf", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "sk_your_private_key")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    respBody, _ := io.ReadAll(resp.Body)
    fmt.Println(string(respBody))
}

With Webhook Callback#

{
    "url": "https://example.com",
    "crawl_mode": "full",
    "callback_url": "https://your-server.com/webhook/enconvert",
    "output_filename": "example-full-site",
    "include_patterns": [".*\\/blog\\/.*", ".*\\/docs\\/.*"],
    "pdf_options": {
        "page_size": "Letter",
        "margins": {"top": 20, "bottom": 20, "left": 15, "right": 15}
    }
}

With Authentication (Password-Protected Site)#

{
    "url": "https://staging.example.com",
    "crawl_mode": "sitemap",
    "auth": {
        "username": "admin",
        "password": "staging-password"
    },
    "cookies": [
        {"name": "session_token", "value": "abc123", "domain": "staging.example.com"}
    ]
}

Error Responses#

Limits#

Frequently asked questions#

How do I convert an entire website to PDF with an API?#

Send a POST request to /v1/convert/website-to-pdf with the site's base url and your private key in the X-API-Key header. The API discovers every page (sitemap or full crawl), converts each one to PDF, bundles them into a ZIP, and returns HTTP 202 with a batch_id you can poll for the download link.

What is the difference between sitemap and full crawl mode?#

crawl_mode: "sitemap" parses the site's sitemap.xml (including nested sitemap indexes) and is available on Indie plans and above. crawl_mode: "full" runs a two-phase crawl (seed discovery from robots.txt, sitemaps, and RSS/Atom feeds, then a breadth-first same-domain link crawl with include_patterns/exclude_patterns filtering) and requires Studio or higher. The default "auto" uses the highest mode your plan allows.

How do I know when my website to PDF job is finished?#

Poll GET /v1/convert/batch/{batch_id} with your private key to get aggregate status, per-URL statuses, and a presigned ZIP download URL, or pass a callback_url to receive a webhook POST on completion. A completion email is also sent to notification_email (or the project owner by default) regardless of success or failure.

Can I archive a password-protected or staging site as PDF?#

Yes, on plans with basic auth access: pass auth with username and password for HTTP Basic Auth applied to every page, inject up to 50 session cookies, or send up to 20 custom headers.

Why does the website to PDF endpoint return 403 Forbidden?#

The most common causes: website capture is not available on the Founding plan, crawl_mode: "full" requires Studio or higher, the discovered page count exceeds your plan's batch size limit, or a requested feature (webhook, basic auth) is not on your plan.