How to Use Stirling PDF REST API Endpoints for Merge, Split, and Convert Operations

Stirling PDF exposes its core PDF-processing capabilities through Spring Boot REST controllers that accept multipart/form-data requests and return binary responses for merge, split, and convert workflows.

The Stirling-Tools/Stirling-PDF repository implements a consistent controller-service-factory pattern across all REST API endpoints. Whether you are combining documents, extracting pages, or converting formats, each operation follows the same architectural blueprint involving MultipartFile handling, CustomPDFDocumentFactory for PDFBox integration, and WebResponseUtils for standardized HTTP responses.

Merge PDFs via REST API

The merge operation combines multiple PDF files into a single document with optional sorting, table-of-contents generation, and signature removal.

Endpoint Details and Request Parameters

The MergeController class handles POST /api/v1/misc/merge-pdfs as defined in app/core/src/main/java/stirling/software/SPDF/controller/api/MergeController.java. It accepts the following parameters through the MergePdfsRequest model:

• fileInput: Array of MultipartFile objects containing the PDFs to combine
• sortType: Sorting algorithm (byName, byDate, byPDFTitle, or orderProvided)
• fileOrder: Newline-separated list of filenames to force a specific merge order when sortType is orderProvided
• removeCertSign: Boolean flag to strip digital certification signatures from the final output
• generateToc: Boolean flag to inject a table of contents page using source filenames

The controller pre-validates each file using pdfDocumentFactory.load() before delegating to PDFBox’s PDFMergerUtility. Post-processing steps remove signatures and generate the TOC when requested. The final document streams back as application/pdf via WebResponseUtils.bytesToWebResponse.

Example: Merge Multiple PDFs with cURL

curl -X POST "http://localhost:8080/api/v1/misc/merge-pdfs?fileOrder=doc2.pdf%0Adoc1.pdf" \
  -H "Accept: application/pdf" \
  -F "fileInput=@/path/to/doc1.pdf" \
  -F "fileInput=@/path/to/doc2.pdf" \
  -F "sortType=orderProvided" \
  -F "removeCertSign=true" \
  -F "generateToc=true" \
  -o merged.pdf

The fileOrder parameter uses URL-encoded newlines (%0A) to sequence files according to the private reorderFilesByProvidedOrder helper method in MergeController.java.

Split PDF into Separate Pages via REST API

The split operation divides a single PDF into individual page files packaged as a ZIP archive.

Endpoint Details and Page Range Handling

The SplitPDFController in app/core/src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java exposes POST /api/v1/general/split-pages. It utilizes the PDFWithPageNums model (located in app/core/src/main/java/stirling/software/SPDF/model/api/PDFWithPageNums.java) to parse page range strings such as 1-3,5,7- into a sorted list of zero-based indexes via request.getPageNumbersList().

The workflow loads the source document once, iterates over split points to create new PDDocument instances using createNewDocumentBasedOnOldDocument, and writes each segment into a ByteArrayOutputStream. The controller packages all segments into a ZipOutputStream and returns application/octet-stream (ZIP format).

Example: Split All Pages into a ZIP Archive

curl -X POST "http://localhost:8080/api/v1/general/split-pages" \
  -H "Accept: application/zip" \
  -F "fileInput=@/path/to/large.pdf" \
  -F "pageNumbers=all" \
  -o split_pages.zip

When pageNumbers=all is specified, the controller splits at every page boundary, producing files named large_0.pdf, large_1.pdf, and so on.

Convert PDFs via REST API

Stirling PDF provides multiple converter controllers annotated with @ConvertApi, each handling specific format transformations while sharing the same temporary file management through TempFileManager and TempFile.

Convert PDF to Images

The ConvertImgPDFController (app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java) handles POST /api/v1/converter/pdf/img using the ConvertToImageRequest model. Key parameters include:

• imageFormat: Output format (png, jpeg, gif, webp)
• singleOrMultiple: "single" creates one image containing all pages; "multiple" creates one image per page
• colorType: Color mode (color, greyscale, blackwhite)
• dpi: Resolution in dots per inch (default 300)
• includeAnnotations: Boolean to rasterize PDF annotations into the output

The controller leverages PDFBox’s PDFRenderer for rasterization, applies color conversions, and returns either a single image or a ZIP archive of images depending on singleOrMultiple.

Convert Office Documents to PDF

For DOCX, XLSX, and other Office formats, the ConvertOfficeController utilizes LibreOffice in headless mode. The endpoint POST /api/v1/converter/file/pdf accepts a single MultipartFile and returns application/pdf.

Example: Convert PDF to Multiple PNG Images

curl -X POST "http://localhost:8080/api/v1/converter/pdf/img" \
  -H "Accept: application/zip" \
  -F "fileInput=@/path/to/report.pdf" \
  -F "imageFormat=png" \
  -F "singleOrMultiple=multiple" \
  -F "colorType=color" \
  -F "dpi=300" \
  -F "includeAnnotations=false" \
  -o report_images.zip

Example: Convert DOCX to PDF

curl -X POST "http://localhost:8080/api/v1/converter/file/pdf" \
  -H "Accept: application/pdf" \
  -F "fileInput=@/path/to/document.docx" \
  -o document.pdf

Common Architecture and Infrastructure Components

All three operation types rely on a shared set of utility classes that ensure consistent behavior and resource management:

• CustomPDFDocumentFactory (app/core/src/main/java/stirling/software/common/service/CustomPDFDocumentFactory.java): Central factory for creating and loading PDDocument instances with caching support
• TempFileManager and TempFile (app/core/src/main/java/stirling/software/common/util/): Scoped temporary file lifecycle management with automatic cleanup after request completion
• WebResponseUtils (app/core/src/main/java/stirling/software/common/util/WebResponseUtils.java): Helper utility to convert byte arrays into Spring ResponseEntity objects with proper Content-Type and Content-Disposition headers
• ExceptionUtils: Standardized error handling that translates PDFBox and LibreOffice exceptions into HTTP-friendly responses

Summary

• Merge endpoint: POST /api/v1/misc/merge-pdfs controlled by MergeController.java supports file reordering, signature removal, and TOC generation
• Split endpoint: POST /api/v1/general/split-pages controlled by SplitPDFController.java parses page ranges via PDFWithPageNums.java and returns ZIP archives
• Convert endpoints: POST /api/v1/converter/pdf/img and POST /api/v1/converter/file/pdf handle image rasterization and Office document conversion respectively
• Shared infrastructure: All endpoints use CustomPDFDocumentFactory for PDF loading and WebResponseUtils for binary response streaming
• Request format: All operations accept multipart/form-data with fileInput parameters and return binary content (PDF or ZIP)

Frequently Asked Questions

What authentication is required for the Stirling PDF REST API?

Stirling PDF does not enforce authentication by default on its REST endpoints. However, when deployed with security configurations enabled (such as OAuth2 or local username/password), the same session cookies or bearer tokens required for the web UI must accompany API requests. Check your deployment’s application.properties for security.enableLogin settings.

How does the API handle large file uploads and memory management?

The API uses TempFileManager to spill large uploads to disk rather than holding them entirely in memory. The CustomPDFDocumentFactory loads PDDocument instances with non-sequential parsing for memory efficiency, and all temporary files created during request processing are automatically deleted when the TempFile object goes out of scope at the end of the HTTP request.

Can I specify custom page ranges when splitting a PDF instead of extracting every page?

Yes. Instead of pageNumbers=all, provide a comma-separated list of ranges such as pageNumbers=1-3,5,7-. The PDFWithPageNums.getPageNumbersList() method parses this string into specific page indexes, and SplitPDFController creates separate PDF documents for each specified segment, packaging them into the returned ZIP file.

What image formats are supported when converting PDFs to images?

According to the ConvertToImageRequest.java model and ConvertImgPDFController.java implementation, supported formats include png, jpeg, gif, and webp. The controller uses PDFBox’s PDFRenderer and respects the dpi, colorType, and includeAnnotations parameters to control output quality and content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}