--- title: "Change PDF page number or labels server-side | Nutrient SDK" canonical_url: "https://www.nutrient.io/guides/document-engine/editor/page-label/" md_url: "https://www.nutrient.io/guides/document-engine/editor/page-label.md" last_updated: "2026-05-30T02:20:01.229Z" description: "Document Engine lets you set labels for pages of a document by sending a multipart request to the /build endpoint and attaching both the input file(s)." --- # Changing PDF page numbers or labels This guide explains how to set PDF page labels in Document Engine as part of a server-side build workflow. For a cross-product overview of how PDF page labels work and how each Nutrient product handles them, refer to the [PDF page labels](https://www.nutrient.io/guides/pdf-page-labels.md) guide. Document Engine lets you set labels for pages of a document by sending a multipart request to the [`/build` endpoint](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API) and attaching both the input file(s) and the [`instructions` JSON](https://www.nutrient.io/api/reference/document-engine/upstream/#model/BuildInstructions). This is done using the `instructions.output.labels` field. This can be useful when, for example, you want PDF readers to show Roman numerals for page labels instead of Arabic numerals. Learn more about the `instructions` schema in our [API Reference](https://www.nutrient.io/api/reference/document-engine/upstream/#model/BuildInstructions). This guide presents examples of setting page labels for 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. ## Setting the Page Label of a File on Disk This example merges two documents together and then sets the label of the first page (index 0) in the merged output to `"i"`, the label of the pages with indexes `1, 2, and 3` to `"intro"`, and the label of the pages with indexes `4, 5, 6, and 7` to `"final"`. As shown in the example, there are multiple ways to specify the index or range of indexes you want to apply a specific label to. You can learn more by checking out our [API Reference](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API). ### SHELL ```shell curl -X POST http://localhost:5000/api/build \ -H "Authorization: Token token=" \ -F document1=@/path/to/example-document1.pdf \ -F document1=@/path/to/example-document2.pdf \ -F instructions='{ "parts": [ { "file": "document1" }, { "file": "document2" } ], "output": { "type": "pdf", "labels": [ { "pageIndex": 0, "label": "i" }, { "pages": { "start": 1, "end": 3 }, "label": "intro" }, { "pages": [ 4, 5, 6, 7 ], "label": "final" } ] } }' \ -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="document1"; filename="example-document1.pdf" Content-Type: application/pdf --customboundary Content-Disposition: form-data; name="document1"; filename="example-document2.pdf" Content-Type: application/pdf --customboundary Content-Disposition: form-data; name="instructions" Content-Type: application/json { "parts": [ { "file": "document1" }, { "file": "document2" } ], "output": { "type": "pdf", "labels": [ { "pageIndex": 0, "label": "i" }, { "pages": { "start": 1, "end": 3 }, "label": "intro" }, { "pages": [ 4, 5, 6, 7 ], "label": "final" } ] } } --customboundary-- ``` ## Setting the Page Label of a File from a URL You can also specify the file to set a page label on using a URL. This example provides a URL to the PDF and then sets the label of the first page to `"i"`. ### 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" } } ], "output": { "type": "pdf", "labels": [ { "pageIndex": 0, "label": "i" } ] } }' \ -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" } } ], "output": { "type": "pdf", "labels": [ { "pageIndex": 0, "label": "i" } ] } } --customboundary-- ``` --- ## Related pages - [Architecture diagram](/guides/document-engine/editor/architecture-diagram.md) - [Add pages to PDFs](/guides/document-engine/editor/add-page.md) - [Document processing and editing server](/guides/document-engine/editor.md) - [Merge multiple PDF files](/guides/document-engine/editor/merge-or-combine.md) - [Password protect PDFs](/guides/document-engine/editor/password-pdfs.md) - [Add watermarks to PDFs](/guides/document-engine/editor/watermark.md)