Log In Sign Up

Docs

Website capture

Render any URL to PDF or image. Async (POST /jobs) or synchronous (POST download.converterer.com/). Both share parameters and auth.

Render any URL to PDF. Two endpoints share the same body parameters: pick async or synchronous depending on whether you want the result streamed back immediately or delivered to your destination’s storage.

Use caseEndpointReturns
You want the PDF in the response bodyPOST https://download.converterer.com/PDF bytes (binary)
You want the PDF in your destination storagePOST https://api.converterer.com/jobsJSON job descriptor

Both endpoints accept either application/x-www-form-urlencoded form data or application/json bodies. Only url is required.

See parameters for the full options surface.

POST https://api.converterer.com/jobs, async render

Queues a render job. The PDF is generated in the background and uploaded to your destination’s storage.

curl -u "$CONVERTERER_API_KEY:" \
  https://api.converterer.com/jobs \
  -d url="https://en.wikipedia.org/wiki/Airplane" \
  -d margin_top=0.5cm \
  -d margin_bottom=0.5cm \
  -d page_size=A4

JSON variant:

curl -u "$CONVERTERER_API_KEY:" \
  -H "Content-Type: application/json" \
  --data @body.json \
  https://api.converterer.com/jobs

Where body.json is:

{
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "footer_template": "<div style=\"width:100%; font-size:12px; text-align:center\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
  "margin_bottom": "2cm"
}

Response: 200 OK

Returns 200 (not 201) for backward compatibility.

{
  "id": "fe748521-5d8f-43d8-9093-7970d2d032d7",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "queued",
  "done": false,
  "object": "job"
}

Use the id to poll GET /jobs/{id} or wait for a webhook notification.

GET https://api.converterer.com/jobs/{id}, fetch a render job

curl -u "$CONVERTERER_API_KEY:" \
  https://api.converterer.com/jobs/fe748521-5d8f-43d8-9093-7970d2d032d7

Response: 200 OK

{
  "id": "fe748521-5d8f-43d8-9093-7970d2d032d7",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "delivered",
  "done": true,
  "object": "job"
}

When status === "delivered", the rendered PDF is in your destination’s storage at {id}.pdf (or your custom file_name). Retrieve it directly from your bucket; see Storage destinations.

POST https://download.converterer.com/, synchronous render

Same request body as POST /jobs, but the request blocks until the PDF is ready and streams it back as the response body. Typical generation times are 5 to 15 seconds. The PDF is also uploaded to your destination’s storage in the background.

curl -u "$CONVERTERER_API_KEY:" \
  https://download.converterer.com/ \
  -d url="https://en.wikipedia.org/wiki/Airplane" \
  -o airplane.pdf
  • Response body: PDF bytes (application/pdf).
  • Response header: x-paperplane-job-id carries the underlying job ID for log correlation.
  • Errors: non-200 with a JSON body of the form {"message": "..."}. Example: 401 {"message":"invalid API key"}.

Use the synchronous endpoint for small, fast pages where blocking the request is acceptable. For large or slow pages, use the async /jobs endpoint with a webhook so your client doesn’t sit on an open connection.

Retry billing

Website capture has a retry-billing rule that file conversion doesn’t:

  • Successful jobs are always billed.
  • The first 3 failed jobs for any given URL are free. From the 4th submission of that same URL onward, a failed job counts toward usage. “Same URL” is matched across every destination on your account.
  • File conversion (/convert) has no retry billing. Failed conversions never count toward usage, by design.

A note on the x-paperplane-job-id header

The download.converterer.com endpoint and several response fields use a paperplane-prefixed header (x-paperplane-job-id). That’s a legacy of the upstream project this API was forked from and is preserved for backward compatibility. Use it as-is; no rename is planned.