--- title: "Add page to PDF server-side | Nutrient" canonical_url: "https://www.nutrient.io/guides/document-engine/editor/add-page/" md_url: "https://www.nutrient.io/guides/document-engine/editor/add-page.md" last_updated: "2026-05-19T09:44:53.443Z" description: "Learn how to insert new pages into PDF documents using the Document Engine's API. Follow our guide for step-by-step examples and instructions." --- # Add pages to PDFs Document Engine lets you add new pages to a document by sending a multipart request to the [`/api/build` endpoint](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Document-Editing/operation/build-document) and attaching the input file(s) and the `instructions` JSON. This guide provides some examples of adding new pages to PDFs. - Ensure [Document Engine is up and running](https://www.nutrient.io/sdk/document-engine/getting-started.md). - Send a [multipart POST request](https://www.baeldung.com/postman-form-data-raw-x-www-form-urlencoded) with [instructions](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API) to Document Engine’s `/api/build` endpoint. For more information, refer to the [API reference](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API) to learn about the `/api/build` endpoint and all the actions you can perform on PDFs with Document Engine. For an overview of multipart requests, refer to the [brief tour of multipart requests](https://www.nutrient.io/blog/a-brief-tour-of-multipart-requests/) blog post. ## Adding a Page to a File on Disk The instructions in this example will insert a new A4-size page after the first page of the document: ### SHELL ```shell curl -X POST http://localhost:5000/api/build \ -H "Authorization: Token token=" \ -F document=@/path/to/example-document.pdf \ -F instructions='{ "parts": [ { "file": "document", "actions": [ { "type": "insertPage", "afterPageIndex": 0, "pageWidth": 595, "pageHeight": 842 } ] } ] }' \ -o result.pdf ``` ### HTTP ```http POST /api/build HTTP/1.1 Content-Type: multipart/form-data; boundary=customboundary Authorization: Token token= --customboundary Content-Disposition: form-data; name="document"; filename="example-document.pdf" Content-Type: application/pdf --customboundary Content-Disposition: form-data; name="instructions" Content-Type: application/json { "parts": [ { "file": "document", "actions": [ { "type": "insertPage", "afterPageIndex": 0, "pageWidth": 595, "pageHeight": 842 } ] } ] } --customboundary-- ``` You can also specify the `beforePageIndex` option for the `insertPage` [action](https://www.nutrient.io/api/reference/document-engine/upstream/#model/BuildInstructions), but note that either `afterPageIndex` or `beforePageIndex` is required, and you cannot provide both. `/build` will return error messages if you attempt a request specifying both options for an `insertPage` action. You can also add a new page using the [`NewPagePart` action](https://www.nutrient.io/api/reference/document-engine/upstream/#model/NewPagePart) instead of the `insertPage` action. This example adds two blank pages after the first page of the document. The instructions in this example will insert two new A4 pages after the first page of the document: ### SHELL ```shell curl -X POST http://localhost:5000/api/build \ -H "Authorization: Token token=" \ -F document=@/path/to/example-document.pdf \ -F instructions='{ "parts": [ { "file": "document", "pages": { "start": 0, "end": 0 } }, { "page": "new", "pageCount": 2 }, { "file": "document", "pages": { "start": 1, "end": 7 } } ] }' \ -o result.pdf ``` ### HTTP ```http POST /api/build HTTP/1.1 Content-Type: multipart/form-data; boundary=customboundary Authorization: Token token= --customboundary Content-Disposition: form-data; name="document"; filename="example-document.pdf" Content-Type: application/pdf --customboundary Content-Disposition: form-data; name="instructions" Content-Type: application/json { "parts": [ { "file": "document", "pages": { "start": 0, "end": 0 } }, { "page": "new", "pageCount": 2 }, { "file": "document", "pages": { "start": 1, "end": 7 } } ] } --customboundary-- ``` ## Adding a Page to a File from a URL To add an A4 page after the first page of the document at the provided URL, use the following code example: ### SHELL ```shell curl -X POST http://localhost:5000/api/build \ -H "Authorization: Token token=" \ -F instructions='{ "parts": [ { "file": { "url": "https://pspdfkit.com/downloads/examples/paper.pdf" }, "actions": [ { "type": "insertPage", "afterPageIndex": 0, "pageWidth": 595, "pageHeight": 842 } ] } ] }' \ -o result.pdf ``` ### HTTP ```http POST /api/build HTTP/1.1 Content-Type: multipart/form-data; boundary=customboundary Authorization: Token token= --customboundary Content-Disposition: form-data; name="instructions" Content-Type: application/json { "parts": [ { "file": { "url": "https://pspdfkit.com/downloads/examples/paper.pdf" }, "actions": [ { "type": "insertPage", "afterPageIndex": 0, "pageWidth": 595, "pageHeight": 842 } ] } ] } --customboundary-- ``` --- ## Related pages - [Document processing and editing server](/guides/document-engine/editor.md) - [Merge multiple PDF files](/guides/document-engine/editor/merge-or-combine.md) - [Changing PDF page numbers or labels](/guides/document-engine/editor/page-label.md) - [Password protect PDFs](/guides/document-engine/editor/password-pdfs.md) - [Add watermarks to PDFs](/guides/document-engine/editor/watermark.md) - [Architecture diagram](/guides/document-engine/editor/architecture-diagram.md)