peasy-pdf

Ruby client for the PeasyPDF API — merge, split, rotate, and compress PDF files. Zero dependencies beyond Ruby stdlib (Net::HTTP, JSON, URI).

Built from PeasyPDF, a comprehensive PDF toolkit offering free online tools for merging, splitting, rotating, compressing, and converting PDF documents. The site includes detailed guides on PDF optimization, accessibility best practices, and format conversion, plus a glossary covering terms from linearization to OCR to PDF/A archival compliance.

Try the interactive tools at peasypdf.com — Merge PDF, Split PDF, Compress PDF, Rotate PDF, and more.

• Install
• Quick Start
• What You Can Do
  • PDF Document Operations
  • Browse Reference Content
  • Search and Discovery
• API Client
  • Available Methods
• Learn More About PDF Tools
• Also Available
• Peasy Developer Tools
• License

gem install peasy-pdf

Or add to your Gemfile:

gem "peasy-pdf"

require "peasy_pdf"

client = PeasyPDF::Client.new

# List available PDF tools
tools = client.list_tools
tools["results"].each do |tool|
  puts "#{tool["name"]}: #{tool["description"]}"
end

The Portable Document Format (PDF) was created by Adobe in 1993 and became an open ISO standard (ISO 32000) in 2008. Today PDF is the most widely used format for document exchange, supporting text, images, forms, digital signatures, and embedded multimedia. PeasyPDF provides tools for every common PDF workflow — from merging invoices into a single file to compressing scanned documents for email delivery.

The PDF specification (ISO 32000-2:2020) supports a remarkably rich feature set including interactive forms (AcroForms and XFA), digital signatures with certificate chains, 3D artwork using U3D and PRC formats, embedded multimedia, and accessibility tagging for screen readers. Linearized PDFs rearrange the internal object structure so that the first page can be displayed before the entire file has been downloaded — critical for web-based PDF viewing where multi-megabyte documents need to appear instantly.

require "peasy_pdf"

client = PeasyPDF::Client.new

# Retrieve the PDF merge tool and inspect its capabilities
tool = client.get_tool("pdf-merge")
puts "Tool: #{tool["name"]}"              # PDF merge tool name
puts "Description: #{tool["description"]}" # How merging works

# List all available PDF tools with pagination
tools = client.list_tools(page: 1, limit: 20)
puts "Total PDF tools available: #{tools["count"]}"

Learn more: Merge PDF Tool · How to Merge PDF Files · PDF Compression Guide

PeasyPDF includes a comprehensive glossary of document format terminology and in-depth guides for common workflows. The glossary covers foundational concepts like PDF linearization (web-optimized PDFs that load page-by-page), OCR (optical character recognition for scanned documents), DPI (dots per inch for print-quality output), and PDF/A (the ISO 19005 archival standard used by governments and libraries worldwide).

PDF compression operates at multiple levels within the document structure. Text and vector graphics are stored as compact operator sequences in content streams, which can be compressed with Flate (zlib) encoding. Embedded images — often the largest component of a PDF — support JPEG, JPEG2000, JBIG2, and CCITT fax compression depending on the image type. A well-optimized PDF applies different compression strategies to different objects: lossy JPEG for photographs, lossless Flate for text-heavy pages, and JBIG2 for scanned black-and-white documents.

require "peasy_pdf"

client = PeasyPDF::Client.new

# Browse the PDF glossary for document format terminology
glossary = client.list_glossary(search: "linearization")
glossary["results"].each do |term|
  puts "#{term["term"]}: #{term["definition"]}"
end

# Read a specific guide on PDF accessibility best practices
guide = client.get_guide("accessible-pdf-best-practices")
puts "Guide: #{guide["title"]} (Level: #{guide["audience_level"]})"

Learn more: PDF Glossary · Accessible PDF Best Practices · How to Convert PDF to Images

The API supports full-text search across all content types — tools, glossary terms, guides, use cases, and format documentation. Search results are grouped by content type, making it easy to find exactly what you need for a specific PDF workflow. Format conversion data covers the full matrix of source-to-target transformations, including quality considerations — converting a vector PDF to a raster format like PNG requires choosing an appropriate DPI (150 for screen viewing, 300 for print, 600 for archival), since this irreversibly flattens scalable content into a fixed pixel grid.

require "peasy_pdf"

client = PeasyPDF::Client.new

# Search across all PDF content — tools, glossary, guides, and formats
results = client.search("compress pdf")
puts "Found #{results["results"]["tools"].length} tools"
puts "Found #{results["results"]["glossary"].length} glossary terms"
puts "Found #{results["results"]["guides"].length} guides"

# Discover format conversion paths — what can PDF convert to?
conversions = client.list_conversions(source: "pdf")
conversions["results"].each do |c|
  puts "#{c["source_format"]} -> #{c["target_format"]}"
end

# Get detailed information about a specific document format
format = client.get_format("pdf")
puts "#{format["name"]} (#{format["extension"]}): #{format["mime_type"]}"

Learn more: REST API Docs · All PDF Tools · All Formats

The client wraps the PeasyPDF REST API using only Ruby standard library — no external dependencies.

require "peasy_pdf"

client = PeasyPDF::Client.new
# Or with a custom base URL:
# client = PeasyPDF::Client.new(base_url: "https://custom.example.com")

# List tools with pagination and filters
tools = client.list_tools(page: 1, limit: 10, search: "compress")

# Get a specific tool by slug
tool = client.get_tool("pdf-merge")
puts "#{tool["name"]}: #{tool["description"]}"

# Search across all content
results = client.search("compress")
puts "Found #{results["results"]["tools"].length} tools"

# Browse the glossary
glossary = client.list_glossary(search: "pdf-a")
glossary["results"].each do |term|
  puts "#{term["term"]}: #{term["definition"]}"
end

# Discover guides
guides = client.list_guides(category: "pdf")
guides["results"].each do |guide|
  puts "#{guide["title"]} (#{guide["audience_level"]})"
end

# List file format conversions
conversions = client.list_conversions(source: "pdf")

# Get format details
format = client.get_format("pdf")
puts "#{format["name"]} (#{format["extension"]}): #{format["mime_type"]}"

All list methods accept keyword arguments: page:, limit:, category:, search:.

Full API documentation at peasypdf.com/developers/. OpenAPI 3.1.0 spec: peasypdf.com/api/openapi.json.

• Tools: Merge PDF · Split PDF · Compress PDF · Rotate PDF · PDF to PNG · All Tools
• Guides: How to Merge PDF Files · PDF Compression Guide · Accessible PDF Best Practices · How to Convert PDF to Images · All Guides
• Glossary: PDF · PDF/A · DPI · OCR · Rasterization · All Terms
• Formats: All Formats
• API: REST API Docs · OpenAPI Spec

Part of the Peasy Tools open-source developer ecosystem.

Embed PeasyPdf widgets on any website with peasy-pdf-embed:

<script src="https://cdn.jsdelivr.net/npm/peasy-pdf-embed@1/dist/embed.min.js"></script>
<div data-peasypdf="entity" data-slug="example"></div>

Zero dependencies · Shadow DOM · 4 themes (light/dark/sepia/auto) · Widget docs

MIT