Ruby HTML to PDF API guide
Use Ruby standard library HTTP clients to generate PDFs from Rails, Sidekiq, Rake tasks, or scripts.
Overview
Build a JSON payload in Ruby, authenticate with X-API-Key, and write the returned PDF bytes to a file.
The API accepts a JSON request body. Send either a public URL or inline HTML in the required html parameter. For normal synchronous conversions, the response body is the generated PDF and should be saved as binary data.
Requirements
- Ruby 3.1 or newer
- The standard net/http and json libraries
- An html2pdf.app API key stored in ENV
Quick start
Replace <your-api-key> or the environment variable with your html2pdf.app API key, then run the example from a trusted backend environment.
Use net/http to post JSON and write the successful response body to document.pdf.
require 'json'
require 'net/http'
require 'uri'
uri = URI('https://api.html2pdf.app/v1/generate')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = ENV.fetch('HTML2PDF_API_KEY')
request.body = { html: 'https://www.example.com' }.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
unless response.is_a?(Net::HTTPSuccess)
raise "PDF generation failed: #{response.code}"
end
File.binwrite('document.pdf', response.body)Ruby examples
These examples cover the next common production flows: generating from inline HTML with options and queuing a callback job.
1. Generate from HTML with page options
Pass layout options with the HTML content when your Ruby app renders the PDF body.
require 'json'
require 'net/http'
require 'uri'
payload = {
html: '<h1>Receipt</h1><p>Paid in full.</p>',
format: 'A4',
marginTop: 40,
marginRight: 32,
marginBottom: 40,
marginLeft: 32,
filename: 'receipt.pdf'
}
uri = URI('https://api.html2pdf.app/v1/generate')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = ENV.fetch('HTML2PDF_API_KEY')
request.body = payload.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
raise response.body unless response.is_a?(Net::HTTPSuccess)
File.binwrite('receipt.pdf', response.body)2. Send an async callback request
Use this shape from a job worker when a webhook should receive the completed PDF.
require 'json'
require 'net/http'
require 'uri'
payload = {
html: 'https://www.example.com/report',
callBackUrl: 'https://your-app.com/webhooks/html2pdf',
state: 'report-1042'
}
uri = URI('https://api.html2pdf.app/v1/generate')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = ENV.fetch('HTML2PDF_API_KEY')
request.body = payload.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
raise response.body unless response.is_a?(Net::HTTPSuccess)Request options
Most integrations start with html and then add options as the document design becomes more specific.
htmlis required and accepts a public URL or raw HTML.format,landscape,width, andheightcontrol page size.marginTop,marginRight,marginBottom, andmarginLeftcontrol whitespace around the rendered page.mediaselectsscreenorprintCSS rendering.callBackUrlswitches the request to asynchronous generation and sends the completed PDF to your webhook.
See the full API parameter reference for every supported field.
Troubleshooting
- Use File.binwrite so Ruby does not treat the PDF as text.
- Run this code in Rails controllers, jobs, or scripts, not in the browser.
- Use ENV.fetch to fail fast when the API key is missing.
If the generated document is blank or missing styles, first confirm that the source URL is public and that required CSS, fonts, and images are reachable by the rendering service.