API Documentation

Batch Processing

Batch processing allows you to convert multiple URLs in a single API request. The URLs are processed asynchronously, and you can poll for results or receive notifications when the batch completes.

Private Keys Only: Batch processing is only available when authenticating with a private API key. Public keys and JWT tokens do not support batch requests.

How It Works

  1. Send a request with an array of URLs in the url parameter.
  2. The API immediately returns a batch_id and begins processing each URL as an individual task.
  3. Poll GET /v1/convert/status/{job_id} with the batch_id to check progress, or configure notifications to be alerted on completion.
  4. Once all tasks complete, retrieve the results from the presigned URLs provided in the status response.

Individual Mode (Default)

By default, each URL in the batch is converted into a separate file. Each file gets its own presigned_url and object_key in the results.

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/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ]
  }'

Response

HTTP 202 Accepted

{
  "success": true,
  "message": "Batch job created",
  "batch_id": "batch_7f3a9c2e",
  "total_tasks": 3,
  "status": "processing"
}

When polling with the batch_id after completion, each task will have its own presigned_url and object_key (see Job Status Polling below).

ZIP Bundle Mode

Set output_format to "zip" to receive all converted files bundled into a single ZIP archive.

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/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ],
    "output_format": "zip"
  }'

Response

HTTP 202 Accepted

{
  "success": true,
  "message": "Batch job created (ZIP bundle)",
  "batch_id": "batch_8d4b1e5f",
  "total_tasks": 3,
  "output_format": "zip",
  "status": "processing"
}

When the batch completes, the status response will include a single presigned_url for the ZIP archive containing all converted files.

Batch Completion

A batch job is considered complete when all individual tasks have either succeeded or failed. If some tasks fail while others succeed, the batch status will reflect partial completion with details for each task.

Batch Parameters Summary

Parameter Type Default Description
url string[] (required) Array of URLs to convert.
output_format string null Set to "zip" to bundle all results into a ZIP archive.
output_filename string null Custom filename for the ZIP archive (only applies when output_format is "zip").
async_mode boolean true (implicit) Batch requests are always asynchronous. This parameter is implicitly true when an array of URLs is provided.
notification_email string null Email address to notify on batch completion.
callback_url string null Webhook URL to receive a POST when the batch completes.
load_media boolean true Load images and media on each page.
enable_scroll boolean true Scroll pages to trigger lazy-loaded content.
handle_sticky_header boolean true Neutralize sticky/fixed headers.
handle_cookies boolean true Dismiss cookie consent banners.
wait_for_images boolean true Wait for all images to load.
single_page boolean false Render each page as a single continuous page.
viewport_width integer 1920 Browser viewport width in pixels.
viewport_height integer 1080 Browser viewport height in pixels.

Job Status Polling

Use the status endpoint to check the progress and results of an async or batch job.

GET https://api.enconvert.com/v1/convert/status/{job_id}

Replace {job_id} with the batch_id returned from the initial request.

Processing State

While the batch is still in progress:

HTTP 200 OK

{
  "success": true,
  "job_id": "batch_7f3a9c2e",
  "status": "processing",
  "total_tasks": 3,
  "completed_tasks": 1,
  "failed_tasks": 0,
  "progress": 33
}

Success State

When all tasks have completed successfully:

HTTP 200 OK

{
  "success": true,
  "job_id": "batch_7f3a9c2e",
  "status": "completed",
  "total_tasks": 3,
  "completed_tasks": 3,
  "failed_tasks": 0,
  "progress": 100,
  "tasks": [
    {
      "url": "https://example.com/page-1",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/page-1.pdf?X-Amz-Algorithm=...",
      "object_key": "live/files/abc123/url-to-pdf/page-1.pdf",
      "file_size": 184320,
      "conversion_time": 3.12
    },
    {
      "url": "https://example.com/page-2",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/page-2.pdf?X-Amz-Algorithm=...",
      "object_key": "live/files/abc123/url-to-pdf/page-2.pdf",
      "file_size": 210944,
      "conversion_time": 4.55
    },
    {
      "url": "https://example.com/page-3",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/page-3.pdf?X-Amz-Algorithm=...",
      "object_key": "live/files/abc123/url-to-pdf/page-3.pdf",
      "file_size": 97280,
      "conversion_time": 2.87
    }
  ]
}

Failed State

When one or more tasks have failed:

HTTP 200 OK

{
  "success": true,
  "job_id": "batch_7f3a9c2e",
  "status": "completed",
  "total_tasks": 3,
  "completed_tasks": 2,
  "failed_tasks": 1,
  "progress": 100,
  "tasks": [
    {
      "url": "https://example.com/page-1",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/page-1.pdf?X-Amz-Algorithm=...",
      "object_key": "live/files/abc123/url-to-pdf/page-1.pdf",
      "file_size": 184320,
      "conversion_time": 3.12
    },
    {
      "url": "https://example.com/page-2",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/page-2.pdf?X-Amz-Algorithm=...",
      "object_key": "live/files/abc123/url-to-pdf/page-2.pdf",
      "file_size": 210944,
      "conversion_time": 4.55
    },
    {
      "url": "https://invalid-url.example",
      "status": "failed",
      "error": "Failed to load page: net::ERR_NAME_NOT_RESOLVED"
    }
  ]
}

Single Async Job

For a single URL submitted with async_mode: true, the status response follows the same structure but with a single task:

HTTP 200 OK

{
  "success": true,
  "job_id": "job_5e2f8a1b",
  "status": "completed",
  "total_tasks": 1,
  "completed_tasks": 1,
  "failed_tasks": 0,
  "progress": 100,
  "tasks": [
    {
      "url": "https://example.com",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/example-com.pdf?X-Amz-Algorithm=...",
      "object_key": "live/files/abc123/url-to-pdf/example-com.pdf",
      "file_size": 184320,
      "conversion_time": 3.72
    }
  ]
}
← URL Converters Job Notifications →