PDF Operations

Overview

All PDF operations are available as POST requests to /api/v1/{operation}. They accept multipart/form-data with one or more PDF files and JSON-encoded parameters.

Common Behavior

• Synchronous (file < 5 MB): Returns 200 with a presigned download URL
• Asynchronous (file >= 5 MB): Returns 202 with a jobId — poll via Jobs API
• Auth: Required for all operations
• File URLs expire after 1 hour (configurable)

Synchronous Response

{
  "success": true,
  "data": {
    "fileId": "output/user/1/abc123.pdf",
    "url": "https://storage.pdflys.com/output/...",
    "expiresAt": "2026-02-25T11:00:00.000Z"
  }
}

Asynchronous Response (202)

{
  "success": true,
  "data": {
    "jobId": "abc-123",
    "status": "queued"
  }
}

---

Document Assembly

Merge

Combine multiple PDFs into one document.

POST /api/v1/merge

Parameter	Type	Required	Description
files	binary[]	Yes	Two or more PDF files

curl -X POST https://api.pdflys.com/api/v1/merge \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@report-q1.pdf" \
  -F "files=@report-q2.pdf" \
  -F "files=@report-q3.pdf"

Split

Split a PDF into multiple documents.

POST /api/v1/split

Parameter	Type	Required	Description
file	binary	Yes	The PDF file to split
mode	string	Yes	ranges, every-page, or every-n
ranges	object[]	If mode=ranges	Array of { start, end } (0-based page indices)
n	number	If mode=every-n	Split every N pages

Response returns multiple files:

{
  "success": true,
  "data": {
    "files": [
      { "fileId": "...", "name": "split-1.pdf", "url": "..." },
      { "fileId": "...", "name": "split-2.pdf", "url": "..." }
    ],
    "expiresAt": "2026-02-25T11:00:00.000Z"
  }
}

# Split by page ranges
curl -X POST https://api.pdflys.com/api/v1/split \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "mode=ranges" \
  -F 'ranges=[{"start":0,"end":4},{"start":5,"end":9}]'

# Split every page
curl -X POST https://api.pdflys.com/api/v1/split \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "mode=every-page"

# Split every 3 pages
curl -X POST https://api.pdflys.com/api/v1/split \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "mode=every-n" \
  -F "n=3"

Extract Pages

Extract specific pages into a new PDF.

POST /api/v1/extract-pages

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
pages	number[]	Yes	0-based page indices to extract

curl -X POST https://api.pdflys.com/api/v1/extract-pages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "pages=[0,2,4]"

Remove Pages

Remove specific pages from a PDF.

POST /api/v1/remove-pages

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
pages	number[]	Yes	0-based page indices to remove

curl -X POST https://api.pdflys.com/api/v1/remove-pages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "pages=[1,3]"

Organize

Reorder pages in a PDF.

POST /api/v1/organize

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
pageOrder	number[]	Yes	New page order as 0-based indices (e.g., [2,0,1])

curl -X POST https://api.pdflys.com/api/v1/organize \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "pageOrder=[2,0,1,3]"

---

Document Transformation

Compress

Reduce PDF file size by rasterizing at lower quality.

POST /api/v1/compress

Parameter	Type	Required	Default	Description
file	binary	Yes	—	The PDF file
level	string	No	medium	low, medium, or high
quality	number	No	—	JPEG quality 0.01–1.0 (overrides level default)
dpi	number	No	—	Target DPI 72–300 (overrides level default)
grayscale	boolean	No	false	Convert to grayscale
removeMetadata	boolean	No	false	Strip document metadata

curl -X POST https://api.pdflys.com/api/v1/compress \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@large-document.pdf" \
  -F "level=high" \
  -F "grayscale=true"

Rotate

Rotate pages in a PDF.

POST /api/v1/rotate

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
rotations	object[]	Yes	Array of { pageIndex, angle }

• pageIndex: 0-based index, or -1 for all pages
• angle: Must be a multiple of 90 (e.g., 90, 180, 270, -90)

curl -X POST https://api.pdflys.com/api/v1/rotate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'rotations=[{"pageIndex":-1,"angle":90}]'

Crop

Crop margins from PDF pages.

POST /api/v1/crop

Parameter	Type	Required	Default	Description
file	binary	Yes	—	The PDF file
crop	object	Yes	—	{ top, right, bottom, left } in PDF points
applyTo	string or number[]	No	"all"	"all" or array of 0-based page indices

curl -X POST https://api.pdflys.com/api/v1/crop \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'crop={"top":50,"right":30,"bottom":50,"left":30}' \
  -F "applyTo=all"

---

Security

Protect

Password-protect a PDF.

POST /api/v1/protect

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
userPassword	string	Yes	Password required to open the PDF
ownerPassword	string	No	Owner password (defaults to userPassword)

curl -X POST https://api.pdflys.com/api/v1/protect \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "userPassword=s3cret"

Unlock

Remove password protection from a PDF.

POST /api/v1/unlock

Parameter	Type	Required	Default	Description
file	binary	Yes	—	The PDF file
password	string	No	""	Current password of the PDF

curl -X POST https://api.pdflys.com/api/v1/unlock \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@protected.pdf" \
  -F "password=s3cret"

Redact

Black out rectangular regions on PDF pages.

POST /api/v1/redact

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
redactions	object[]	Yes	Array of { pageIndex, x, y, width, height }

All coordinates are in PDF points with origin at bottom-left.

curl -X POST https://api.pdflys.com/api/v1/redact \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'redactions=[{"pageIndex":0,"x":100,"y":700,"width":200,"height":20}]'

---

Annotation

Watermark

Add a text or image watermark.

POST /api/v1/watermark

Parameter	Type	Required	Default	Description
file	binary	Yes	—	The PDF file
mode	string	Yes	—	text or image
text	string	If mode=text	—	Watermark text
image	binary	If mode=image	—	Watermark image file
imageType	string	If mode=image	—	png or jpg
imageWidth	number	No	—	Image width in PDF points
fontSize	number	No	—	Font size for text mode
fontColor	object	No	—	{ r, g, b } (0–1 range)
opacity	number	No	0.5	0–1
rotation	number	No	0	Degrees
position	string	No	center	center, diagonal, top-left, top-right, bottom-left, bottom-right
pages	string or number[]	No	"all"	"all" or array of 0-based page indices

# Text watermark
curl -X POST https://api.pdflys.com/api/v1/watermark \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "mode=text" \
  -F "text=CONFIDENTIAL" \
  -F "position=diagonal" \
  -F "opacity=0.3"

# Image watermark
curl -X POST https://api.pdflys.com/api/v1/watermark \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "mode=image" \
  -F "image=@logo.png" \
  -F "imageType=png" \
  -F "position=bottom-right" \
  -F "opacity=0.5"

Sign

Overlay signature images onto PDF pages.

POST /api/v1/sign

Parameter	Type	Required	Default	Description
file	binary	Yes	—	The PDF file
signatures	object[]	Yes	—	Array of signature placements

Each signature object:

Field	Type	Required	Default	Description
pageIndex	number	Yes	—	0-based page index
imageField	string	Yes	—	Name of the multipart field containing the signature image
imageType	string	No	png	png or jpg
x	number	Yes	—	X coordinate (PDF points)
y	number	Yes	—	Y coordinate (PDF points)
width	number	Yes	—	Width in PDF points
height	number	Yes	—	Height in PDF points
dateText	string	No	—	Date text drawn below signature
additionalText	string	No	—	Additional text below date

curl -X POST https://api.pdflys.com/api/v1/sign \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@contract.pdf" \
  -F "sig1=@signature.png" \
  -F 'signatures=[{"pageIndex":0,"imageField":"sig1","imageType":"png","x":350,"y":100,"width":150,"height":50,"dateText":"2026-02-25"}]'

Highlight

Add colored highlight overlays to rectangular regions.

POST /api/v1/highlight

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
highlights	object[]	Yes	Array of { page, x, y, width, height, color?, opacity? }

Field	Type	Default	Description
page	number	—	0-based page index
x, y	number	—	Position (PDF points, bottom-left origin)
width, height	number	—	Size in PDF points
color	string	#FFFF00	Hex color
opacity	number	0.35	0–1

curl -X POST https://api.pdflys.com/api/v1/highlight \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'highlights=[{"page":0,"x":50,"y":700,"width":400,"height":15,"color":"#FFFF00"}]'

Add Text

Add text annotations to PDF pages.

POST /api/v1/add-text

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
items	object[]	Yes	Array of text items

Each text item:

Field	Type	Default	Description
text	string	—	Text content (required)
page	number	—	0-based page index (required)
x, y	number	—	Position in PDF points (required)
fontSize	number	12	1–200
fontFamily	string	Helvetica	Helvetica, TimesRoman, or Courier
color	string	#000000	Hex color
opacity	number	1	0–1

curl -X POST https://api.pdflys.com/api/v1/add-text \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'items=[{"text":"APPROVED","page":0,"x":400,"y":750,"fontSize":24,"color":"#008000"}]'

Add Shapes

Draw shapes (rectangles, circles, lines) on PDF pages.

POST /api/v1/add-shapes

Parameter	Type	Required	Description
file	binary	Yes	The PDF file
shapes	object[]	Yes	Array of shape objects

Rectangle:

Field	Type	Default	Description
type	"rectangle"	—	Required
page	number	—	0-based page index
x, y	number	—	Position (bottom-left origin)
width, height	number	—	Size (positive)
fillColor	string	—	Hex color (optional)
strokeColor	string	—	Hex color (optional)
strokeWidth	number	—	Line width (optional)
opacity	number	1	0–1

Circle/Ellipse:

Field	Type	Default	Description
type	"circle"	—	Required
page	number	—	0-based page index
x, y	number	—	Center position
radiusX, radiusY	number	—	Radii (positive)
fillColor, strokeColor	string	—	Optional hex colors
strokeWidth	number	—	Optional
opacity	number	1	0–1

Line:

Field	Type	Default	Description
type	"line"	—	Required
page	number	—	0-based page index
startX, startY	number	—	Start point
endX, endY	number	—	End point
strokeColor	string	—	Optional hex color
strokeWidth	number	—	Optional
opacity	number	1	0–1

curl -X POST https://api.pdflys.com/api/v1/add-shapes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'shapes=[{"type":"rectangle","page":0,"x":50,"y":700,"width":200,"height":50,"strokeColor":"#FF0000","strokeWidth":2}]'

Page Numbers

Add page numbers to a PDF.

POST /api/v1/page-numbers

Parameter	Type	Default	Description
file	binary	—	The PDF file (required)
position	string	BC	TL, TC, TR, BL, BC, BR
format	string	{n}	{n}, Page {n}, {n} of {total}, Page {n} of {total}, - {n} -
startNumber	number	1	Starting page number
fontSize	number	12	4–72
fontColor	string	#000000	Hex color
applyTo	string or object	"all"	"all" or { start, end } (0-based inclusive range)
skipFirst	boolean	false	Skip the first page

curl -X POST https://api.pdflys.com/api/v1/page-numbers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "position=BC" \
  -F "format=Page {n} of {total}" \
  -F "skipFirst=true"

---

Conversion

Image to PDF

Convert one or more images into a PDF.

POST /api/v1/image-to-pdf

Parameter	Type	Default	Description
images	binary[]	—	Image files: JPEG, PNG, or WebP (required, min 1)
pageSize	string	fit	fit (match image), a4, or letter
orientation	string	portrait	portrait or landscape
margin	number	0	Margin in PDF points (0–100)

curl -X POST https://api.pdflys.com/api/v1/image-to-pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "images=@scan1.jpg" \
  -F "images=@scan2.jpg" \
  -F "pageSize=a4"

PDF to Image

Convert PDF pages to images (JPG, PNG, or WebP).

POST /api/v1/pdf-to-image

Parameter	Type	Default	Description
file	binary	—	The PDF file (required)
format	string	jpg	jpg, png, or webp
dpi	number	150	Resolution 72–300
quality	number	0.85	Image quality 0.01–1.0 (JPEG/WebP)
pages	number[]	all	0-based page indices (optional — omit for all pages)

Response returns multiple files:

{
  "success": true,
  "data": {
    "files": [
      { "fileId": "...", "name": "page-1.jpg", "url": "..." },
      { "fileId": "...", "name": "page-2.jpg", "url": "..." }
    ],
    "expiresAt": "2026-02-25T11:00:00.000Z"
  }
}

curl -X POST https://api.pdflys.com/api/v1/pdf-to-image \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "format=png" \
  -F "dpi=300" \
  -F "pages=[0,1,2]"

PDF to JPG

Shorthand for converting PDF pages to JPEG images.

POST /api/v1/pdf-to-jpg

Parameter	Type	Default	Description
file	binary	—	The PDF file (required)
dpi	number	150	Resolution 72–300
quality	number	0.85	JPEG quality 0.01–1.0
pages	number[]	all	0-based page indices (optional)

curl -X POST https://api.pdflys.com/api/v1/pdf-to-jpg \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "dpi=200"

---

Analysis

Compare PDFs

Compare two PDFs and report text and/or visual differences.

POST /api/v1/compare

Parameter	Type	Default	Description
file1	binary	—	First PDF (required)
file2	binary	—	Second PDF (required)
mode	string	both	text, visual, or both

curl -X POST https://api.pdflys.com/api/v1/compare \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file1=@version1.pdf" \
  -F "file2=@version2.pdf" \
  -F "mode=both"