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`

Note

Compare always runs synchronously regardless of file size.

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"