Chromium PDF Service

Appearance

API Endpoints ​

Interactive API Documentation

Swagger UI is available at /docs in development mode. You can explore and test all endpoints interactively.

PDF Generation ​

Generate PDF from HTML ​

bash
POST /api/pdf/from-html
Content-Type: application/json
json
{
  "requestedKey": "invoice-12345",
  "html": "<html><body><h1>Hello World</h1></body></html>",
  "options": {
    "pdf": {
      "format": "A4",
      "printBackground": true
    }
  }
}

Generate PDF from URL ​

bash
POST /api/pdf/from-url
Content-Type: application/json
json
{
  "requestedKey": "website-snapshot",
  "url": "https://example.com",
  "options": {
    "browser": {
      "timeout": 30000,
      "viewport": { "width": 1920, "height": 1080 }
    }
  }
}

Generate PDF with Custom Dimensions ​

json
{
  "requestedKey": "custom-size-pdf",
  "url": "https://example.com",
  "options": {
    "browser": {
      "viewport": { "width": 400, "height": 800 }
    },
    "pdf": {
      "width": 400,
      "height": 800,
      "printBackground": true
    }
  }
}

Generate PDF with Loading Rules ​

json
{
  "requestedKey": "spa-page",
  "url": "https://example.com/dashboard",
  "options": {
    "browser": {
      "timeout": 60000,
      "waitForSelector": "#chart-container",
      "waitAfter": 2000
    },
    "pdf": {
      "format": "A4",
      "printBackground": true
    }
  }
}

TIP

This waits for the #chart-container element to appear, then waits an additional 2 seconds before generating the PDF.

Generate PDF with Animations Disabled ​

json
{
  "requestedKey": "no-animation-pdf",
  "url": "https://example.com/animated-page",
  "options": {
    "browser": {
      "disableAnimations": true
    },
    "pdf": {
      "format": "A4",
      "printBackground": true
    }
  }
}

Why disable animations?

CSS animations and transitions can cause elements to be captured mid-animation, resulting in invisible, partially visible, or incorrectly positioned elements in the PDF. This option injects CSS to disable all animations and sets prefers-reduced-motion: reduce for reliable rendering.

Generate PDF with Custom Headers ​

json
{
  "requestedKey": "auth-page",
  "url": "https://example.com/protected",
  "options": {
    "browser": {
      "userAgent": "Mozilla/5.0 Custom Agent",
      "extraHTTPHeaders": {
        "Authorization": "Bearer your-token",
        "X-Custom-Header": "custom-value"
      }
    }
  }
}

Generate PDF from File ​

bash
POST /api/pdf/from-file
Content-Type: multipart/form-data

file: <HTML file>
requestedKey: report-001
options: {"pdf": {"format": "Letter"}}

Screenshot Generation ​

Generate Screenshot from HTML ​

bash
POST /api/screenshot/from-html
Content-Type: application/json
json
{
  "requestedKey": "page-capture-001",
  "html": "<html><body><h1>Hello World</h1></body></html>",
  "options": {
    "screenshot": {
      "type": "png",
      "fullPage": true
    }
  }
}

Generate Screenshot from URL ​

bash
POST /api/screenshot/from-url
Content-Type: application/json
json
{
  "requestedKey": "website-screenshot",
  "url": "https://example.com",
  "options": {
    "browser": {
      "viewport": { "width": 1920, "height": 1080 }
    },
    "screenshot": {
      "type": "png",
      "fullPage": true
    }
  }
}

Generate JPEG Screenshot with Quality ​

json
{
  "requestedKey": "compressed-screenshot",
  "url": "https://example.com",
  "options": {
    "screenshot": {
      "type": "jpeg",
      "quality": 80,
      "fullPage": true
    }
  }
}

Capture Specific Region ​

json
{
  "requestedKey": "region-capture",
  "url": "https://example.com",
  "options": {
    "screenshot": {
      "type": "png",
      "fullPage": false,
      "clip": {
        "x": 0,
        "y": 0,
        "width": 800,
        "height": 600
      }
    }
  }
}

TIP

Use clip to capture a specific region of the page. When using clip, set fullPage to false.

Transparent Background (PNG only) ​

json
{
  "requestedKey": "transparent-screenshot",
  "html": "<html><body style='background: transparent;'><h1>Hello</h1></body></html>",
  "options": {
    "screenshot": {
      "type": "png",
      "omitBackground": true
    }
  }
}

Generate Screenshot from File ​

bash
POST /api/screenshot/from-file
Content-Type: multipart/form-data

file: <HTML file>
requestedKey: screenshot-001
options: {"screenshot": {"type": "png", "fullPage": true}}

Get Screenshot Job Status ​

bash
GET /api/screenshot/status/:requestedKey

Cancel/Remove Screenshot Job ​

bash
DELETE /api/screenshot/:requestedKey

Download Screenshot ​

bash
GET /api/screenshot/download/:requestedKey

Downloads the generated screenshot file. Returns the image with appropriate Content-Type (image/png or image/jpeg).

Response Headers:

  • Content-Type: image/png or image/jpeg
  • Content-Disposition: attachment; filename="<filename>"
  • Content-Length: File size in bytes

Error Responses:

  • 404 - Job not found or file not found
  • 409 - Screenshot not ready (still processing or failed)

Job Management ​

Get Job Status ​

bash
GET /api/pdf/status/:requestedKey

Response:

json
{
  "requestedKey": "invoice-12345",
  "status": "completed",
  "progress": 100,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:05.000Z",
  "filePath": "pdf-files/15-01-2025/invoice-12345__15-01-2025_10-30-05.pdf"
}

Cancel Job ​

bash
DELETE /api/pdf/cancel/:requestedKey

Download PDF ​

bash
GET /api/pdf/download/:requestedKey

Queue Statistics ​

bash
GET /api/pdf/queue

Health Checks ​

bash
GET /health       # Basic health check
GET /health/ready # Readiness probe
GET /health/live  # Liveness probe with queue stats

Settings ​

Get Current Settings ​

bash
GET /api/settings

Update Settings ​

bash
PUT /api/settings
Content-Type: application/json
json
{
  "browser": {
    "maxConcurrent": 5
  },
  "queue": {
    "maxSize": 200
  }
}

Reset to Defaults ​

bash
POST /api/settings/reset

Released under the MIT License.

Copyright © 2025