PDFLoom Logo

Convert

The Convert APIs turn content into shareable PDFs. Each request charges credits based on the resulting file size (1 credit per ~5 MB) and returns a signed S3 URL valid for 30 minutes.

POST/v1/convert/url

Convert a URL to PDF

Render an HTTPS URL and save it as a PDF.

Required attributes

  • Name
    url
    Type
    string
    Description

    Fully-qualified URL (must be reachable over HTTPS).

Optional attributes

  • Name
    callback_url
    Type
    string
    Description

    HTTPS endpoint to notify when the PDF is ready.

  • Name
    engine_options
    Type
    object
    Description

    Browser-level tuning.

    • Name
      timeout
      Type
      integerDefault: 30000
      Description

      Timeout in milliseconds before aborting navigation.

    • Name
      waitForNetworkToIdle
      Type
      booleanDefault: false
      Description

      When true, waits for network to quiet before printing.

  • Name
    options
    Type
    object
    Description

    Page layout settings (margins accept CSS units such as mm, cm, in, or px).

    • Name
      format
      Type
      stringDefault: A4
      Description

      Page size (Letter, A4, etc.).

    • Name
      landscape
      Type
      booleanDefault: false
      Description

      Rotate the page 90°.

    • Name
      margin
      Type
      object
      Description

      Page margins in CSS units (e.g., "10mm").

    • Name
      printBackground
      Type
      booleanDefault: false
      Description

      Include background images/colors.

    • Name
      omitBackground
      Type
      booleanDefault: false
      Description

      Render with transparent background.

    • Name
      scale
      Type
      numberDefault: 1
      Description

      Zoom factor between 0.1 and 2.

    • Name
      displayHeaderFooter
      Type
      booleanDefault: false
      Description

      Enable header/footer templates.

    • Name
      headerTemplate
      Type
      string
      Description

      HTML snippet for page header (supports class="title", pageNumber, etc.).

    • Name
      footerTemplate
      Type
      string
      Description

      HTML snippet for footer.

    • Name
      pageRanges
      Type
      string
      Description

      Specific pages to include (e.g., "1-3,8").

Request

POST
/v1/convert/url
curl -X POST https://api.pdfloom.com/v1/convert/url \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com",
    "callback_url": "https://example.com/webhook",
    "options": {
      "format": "A4",
      "margin": { "top": "10mm", "left": "10mm" }
    }
  }'

Response

{
  "success": true,
  "response": "https://pdfloom-processed.s3.amazonaws.com/generated/pdf/71f1a...pdf?X-Amz-Expires=1800",
  "fileSize": 6139
}

Signed URLs expire after 30 minutes. Download the file immediately and store it yourself if you need permanent access.

POST/v1/convert/html

Convert HTML to PDF

Post raw HTML and optional assets to render server-side.

Required attributes

  • Name
    content
    Type
    string
    Description

    HTML markup.

Optional attributes

  • Name
    assets
    Type
    array
    Description

    List of objects with filename + base64 content to preload CSS/JS.

  • Name
    callback_url
    Type
    string
    Description

    HTTPS callback for async workflows.

  • Name
    options
    Type
    object
    Description

    Same settings as the URL convert endpoint (format, margins, headers, etc.).

cURL

curl -X POST https://api.pdfloom.com/v1/convert/html \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": "<html><body><h1>Hello PDFLoom</h1></body></html>",
    "assets": [
      {"filename": "styles.css", "content": "Ym9keSB7IGZvbnQtZmFtaWx5OiBzYW5zLXNlcmlmOyB9" }
    ],
    "options": { "format": "A4", "printBackground": true }
  }'

<?php
$client = new GuzzleHttp\Client();
$response = $client->post('https://api.pdfloom.com/v1/convert/html', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Content-Type'  => 'application/json',
        'Idempotency-Key' => uniqid('req_', true),
    ],
    'json' => [
        'content' => '<html><body><h1>Hello</h1></body></html>',
        'options' => ['format' => 'Letter'],
    ],
]);
POST/v1/convert/docs

Convert uploaded documents

Use the doc conversion endpoint for Office files. Upload the file directly with multipart form-data.

Required attributes

  • Name
    file
    Type
    file
    Description

    Multipart field containing the document (doc, docx, xls, xlsx, ppt, pptx). Max size 10 MB.

Optional attributes

  • Name
    callback_url
    Type
    string
    Description

    HTTPS webhook notified on completion.

cURL (multipart)

curl -X POST https://api.pdfloom.com/v1/convert/docs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@./invoice.docx" \
  -F "callback_url=https://example.com/webhook"

Authenticated capture (convert + screenshot)

Authenticated capture lets the renderer log in on your behalf before generating a PDF. Add an auth block when the target page sits behind authentication (headers, cookies, form login, or a token-injection script). HTTPS is required for auth URLs; script-based auth can be disabled by your workspace admin.

Limits & safeguards

  • HTML payload max 512 KB; assets max 10 items, 200 KB each.
  • Auth constraints: max 20 headers/cookies, 3 scripts, wait timeout ≤ 60s.
  • Auth requests are rate-limited (default 30/min over 60s). Repeated auth calls with the same token may return 429.
    Callbacks include X-PDFLoom-Signature when CALLBACK_SIGNING_SECRET is set—verify it in your handler.
  • Name
    auth.type
    Type
    string
    Description

    One of header, bearer, basic, cookie, form, or script.

  • Name
    auth.headers
    Type
    object
    Description

    Custom headers map (when type=header).

  • Name
    auth.token
    Type
    string
    Description

    Bearer token (when type=bearer).

  • Name
    auth.username
    Type
    string
    Description

    Username (when type=basic).

  • Name
    auth.password
    Type
    string
    Description

    Password (when type=basic).

  • Name
    auth.cookies
    Type
    array
    Description

    Cookies with name, value, domain, optional path, secure, httpOnly (when type=cookie).

  • Name
    auth.login_url
    Type
    string
    Description

    HTTPS login URL (when type=form).

  • Name
    auth.credentials
    Type
    object
    Description

    Key/value pairs to fill into selectors (when type=form).

  • Name
    auth.selectors
    Type
    object
    Description

    CSS selectors for fields + submit button (when type=form).

  • Name
    auth.scripts
    Type
    array
    Description

    JS snippets to set tokens/localStorage (when type=script).

  • Name
    auth.wait
    Type
    object
    Description

    Optional { selector, waitUntil, timeoutMs } to pause after auth before capture.

Example — bearer header + wait for a selector:

cURL

curl -X POST https://api.pdfloom.com/v1/convert/url \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/reports",
    "auth": {
      "type": "bearer",
      "token": "YOUR_SESSION_TOKEN",
      "wait": { "selector": "#reports-table", "waitUntil": "networkidle2" }
    },
    "options": { "format": "Letter" }
  }'

Example — form login (also works for /v1/screenshot/url):

await fetch('https://api.pdfloom.com/v1/screenshot/url', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://app.example.com/dashboard',
    auth: {
      type: 'form',
      login_url: 'https://app.example.com/login',
      credentials: { email: 'user@example.com', password: 's3cret!' },
      selectors: { email: '#email', password: '#password', submit: 'button[type=submit]' },
      wait: { selector: '#charts-ready', waitUntil: 'networkidle2', timeoutMs: 15000 }
    },
    options: { type: 'png', fullPage: true }
  })
})

Keep auth tokens short-lived, never reuse idempotency keys with different auth, and avoid sending production credentials to non-production hosts. Set AUTH_ALLOW_SCRIPT=false if you want to block script-based auth in your environment.

Error responses

Most failures use the standard payload documented on the Errors page. Two common examples:

{
  "success": false,
  "message": "Insufficient credits.",
  "status": 402
}

{
  "success": false,
  "message": "This idempotency key is already being processed.",
  "status": 409
}

{
  "success": false,
  "message": "The url field must be a valid URL.",
  "status": 422,
  "details": {"url": ["The url format is invalid."]}
}

Was this page helpful?