API Overview

Use this page as your checklist before calling any endpoint: authenticate requests, respect rate limits, understand credit usage, and set up callbacks/idempotency headers for reliability.

Authentication

Generate tokens from Dashboard → Keys.
Send them as bearer tokens: Authorization: Bearer pl_xxx.
Tokens inherit the permissions of the account that created them.

Example request

curl -X GET https://api.pdfloom.com/v1/convert/url \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Never embed API tokens in browser code or public repositories. Rotate them if they leak.

Authenticated capture requests (those with an auth block) are throttled by default at 30 requests/minute over 60 seconds. Regular requests are not globally throttled unless configured by your deployment.

Use backoff/retry when you receive HTTP 429.
Long-running conversions count toward the limit as soon as the request starts.

Response format

Successful responses follow this schema:

{
  "success": true,
  "response": "https://pdfloom-processed.s3.amazonaws.com/generated/pdf/<uuid>.pdf?...",
  "fileSize": 6139
}

response is a signed S3 URL that expires in 30 minutes. Download or proxy it immediately.
fileSize helps you predict credit consumption (5 KB = 1 credit).

Errors return HTTP 4xx/5xx with success: false and a descriptive message:

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

See Errors for common codes (402, 409, 422).

Credits

Each request deducts ceil(fileSize / (5 * 1024 * 1024)) credits (~1 credit per 5 MB).
Credit use is logged per request in the dashboard.
Generator failures do not charge credits; you’ll receive success: false.

Optional fields & callbacks

Field	Applies to	Description
`callback_url`	All convert/screenshot endpoints	HTTPS URL notified when processing finishes (respond with 2xx to acknowledge).
`engine_options.timeout`	URL & HTML endpoints	Override the default 30s timeout.
`engine_options.waitForNetworkToIdle`	URL & HTML endpoints	Wait until network is idle before snapshotting.
`assets`	`/v1/convert/html`, `/v1/screenshot/html`	Array of `{ filename, content }` attachments referenced by your HTML.
`options.*`	All endpoints	See the Convert/Screenshot references for per-feature options (format, margins, clip, etc.).
`auth`	URL & HTML convert/screenshot	Use bearer/header/cookie/basic/form/script auth to capture behind login. HTTPS required; see Authenticated capture. Auth calls are rate-limited (default 30/min).

Callbacks must use HTTPS. Callback retries are not automatic—log the attempt if you need auditing.

Idempotency

Provide an Idempotency-Key header for every request (UUID recommended). We store keys for five minutes:

Reusing a key while a request is running returns HTTP 409 with message: "This idempotency key is already being processed."
Reusing a key after completion returns the cached response and avoids double-charging credits.

-H "Idempotency-Key: 6b2f7c5a-1cb2-42b2-a099-42f1e2f729c7"

Webhooks

Paddle webhooks hit /paddle/webhook and are signature-verified.
Your own conversion callbacks (callback_url) receive the original payload plus result metadata. If you configure CALLBACK_SIGNING_SECRET, verify the X-PDFLoom-Signature header in your handler.

Need more detail? Jump to Authentication, Errors, or the Convert and Screenshot references.

SDK quickstart

Each SDK example should include:

Authorization: Bearer ... header with your API token
Content-Type: application/json
Idempotency-Key header
Optional callback_url where you acknowledge receipt with a 2xx response

await fetch('https://api.pdfloom.com/v1/convert/html', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PDFLOOM_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    content: '<html>...</html>',
    callback_url: 'https://example.com/conversion-webhook',
    options: { format: 'A4' },
  }),
})

import os, uuid, requests

resp = requests.post(
  'https://api.pdfloom.com/v1/convert/url',
  headers={
    'Authorization': f"Bearer {os.environ['PDFLOOM_TOKEN']}",
    'Content-Type': 'application/json',
    'Idempotency-Key': str(uuid.uuid4()),
  },
  json={
    'url': 'https://example.com',
    'callback_url': 'https://example.com/webhook',
  },
)
print(resp.json())

<?php
$client = new GuzzleHttp\Client();
$response = $client->post('https://api.pdfloom.com/v1/convert/url', [
  'headers' => [
    'Authorization' => 'Bearer '.getenv('PDFLOOM_TOKEN'),
    'Content-Type' => 'application/json',
    'Idempotency-Key' => uniqid('req_', true),
  ],
  'json' => [
    'url' => 'https://example.com',
    'callback_url' => 'https://example.com/webhook',
  ],
]);