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

> Easily merge, split, and convert PDFs using Stirling PDF REST API endpoints. Learn how to leverage these powerful tools for your document workflows with multipart data requests.

- Repository: [Stirling Tools/Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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

```bash
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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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

```bash
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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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

```bash
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

```bash
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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/MergeController.java) supports file reordering, signature removal, and TOC generation
- **Split endpoint**: `POST /api/v1/general/split-pages` controlled by [`SplitPDFController.java`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/SplitPDFController.java) parses page ranges via [`PDFWithPageNums.java`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/ConvertToImageRequest.java) model and [`ConvertImgPDFController.java`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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.