Screenshot

Use the Screenshot APIs to capture URLs or HTML snippets as PNG/JPEG/WEBP images. Each request costs credits proportional to image size and responds with a signed S3 URL (valid for 30 minutes).

POST/v1/screenshot/url

Take a screenshot of a URL

Supply a public HTTPS URL to render.

Required attributes

Name
url
Type
string
Description
Fully-qualified HTTPS URL to capture.

Optional attributes

Name
callback_url
Type
string
Description
HTTPS endpoint to notify once the capture finishes (optional).
Name
engine_options
Type
object
Description
Screenshot engine controls.
- Name
  timeout
  Type
  integerDefault: 30000
  Description
  Timeout in milliseconds before aborting navigation.
- Name
  waitForNetworkToIdle
  Type
  booleanDefault: false
  Description
  When true, waits for network to be idle before capturing.
Name
options
Type
object
Description
Visual output options.
- Name
  type
  Type
  stringDefault: png
  Description
  Output image type (png, jpeg, or webp).
- Name
  fullPage
  Type
  booleanDefault: false
  Description
  Capture the full scroll height instead of the viewport height.
- Name
  captureBeyondViewport
  Type
  booleanDefault: false
  Description
  Attempt to capture content beyond the viewport (Chromium experimental flag).
- Name
  omitBackground
  Type
  booleanDefault: false
  Description
  Make the background transparent (only for PNG/WebP).
- Name
  quality
  Type
  integer
  Description
  JPEG quality (1-100). Only applies when type is jpeg.
- Name
  clip
  Type
  object
  Description
  Crop rectangle in CSS pixels.
  Name
  x
  Type
  integer
  Description
  Left offset.
  Name
  y
  Type
  integer
  Description
  Top offset.
  Name
  width
  Type
  integer
  Description
  Width of the clip.
  Name
  height
  Type
  integer
  Description
  Height of the clip.
  Name
  scale
  Type
  numberDefault: 1
  Description
  Device scale factor (usually 1 or 2).

Request

POST

/v1/screenshot/url

curl -X POST https://api.pdfloom.com/v1/screenshot/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": {
      "type": "png",
      "fullPage": true
    }
  }'

Response

{
  "success": true,
  "response": "https://pdfloom-processed.s3.amazonaws.com/generated/ss/7c9b1f9c.png?...",
  "fileSize": 65740
}

POST/v1/screenshot/html

Take a screenshot of HTML content

Post raw HTML or templated markup and receive an image.

Required attributes

Name
content
Type
string
Description
HTML string to render.

Optional attributes

Name
assets
Type
array
Description
Additional resources (CSS/JS) referenced by content.
Name
callback_url
Type
string
Description
HTTPS webhook to notify on completion.
Name
options
Type
object
Description
Same as /v1/screenshot/url (type, fullPage, clip, quality, etc.).

cURL

curl -X POST https://api.pdfloom.com/v1/screenshot/html \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": "<html><body><h1>Screenshot me</h1></body></html>",
    "options": {
      "type": "png",
      "fullPage": false
    }
  }'

import requests, uuid

response = requests.post(
  'https://api.pdfloom.com/v1/screenshot/html',
  headers={
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Idempotency-Key': str(uuid.uuid4()),
  },
  json={
    'content': '<html><body><h1>Screenshot me</h1></body></html>',
    'options': {'type': 'jpeg', 'quality': 80},
  },
)
print(response.json())

Authenticated capture (screenshot)

Authenticated capture lets the renderer log in on your behalf before taking a screenshot. Add an auth block when the target page is behind login (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
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 auth + wait:

cURL

curl -X POST https://api.pdfloom.com/v1/screenshot/url \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "auth": {
      "type": "bearer",
      "token": "YOUR_SESSION_TOKEN",
      "wait": { "selector": "#chart", "waitUntil": "networkidle2" }
    },
    "options": { "type": "png", "fullPage": true }
  }'

Example — form login:

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/reports',
    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: '#reports-table', waitUntil: 'networkidle2', timeoutMs: 15000 }
    },
    options: { type: 'jpeg', quality: 0.9 }
  })
})

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

Screenshot endpoints return the same structure as convert. Expect HTTP 4xx for validation issues and 503 when the renderer is temporarily unavailable.

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

{
  "success": false,
  "message": "The options.type field must be one of: png, jpeg, webp.",
  "status": 422
}

{
  "success": false,
  "message": "Generator service unavailable.",
  "status": 503
}