---
title: "PDF page manipulation API"
canonical_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-page-manipulation-api/"
md_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-page-manipulation-api.md"
last_updated: "2026-07-06T00:00:00.000Z"
description: "Add blank pages, delete pages, duplicate pages, reorder pages, and set page labels in PDF files using Nutrient DWS Processor API."
---

# PDF page manipulation API

Use the PDF page manipulation API to add blank pages, delete pages, duplicate pages, reorder pages, and set page labels in PDF documents. The [`/build` endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) handles page manipulation with the `parts` array.

Each `parts` item contributes pages to the output PDF. Combine file parts, page ranges, and new blank page parts to build a new PDF in the order you need.

For signup, pricing, and task-level examples, refer to these pages:

- [Add page API task page](https://www.nutrient.io/api/add-page-api/)

- [Delete PDF page API task page](https://www.nutrient.io/api/delete-pdf-page-api/)

- [Duplicate PDF page API task page](https://www.nutrient.io/api/duplicate-pdf-page-api/)

## Add a blank page

The following example inserts one new US Letter page after the first page of `document.pdf`.

Page indexes are zero-based, so page `0` is the first page. The `end` value is inclusive, so `{ "start": 0, "end": 0 }` includes only the first page.

### Shell

### Shell (Windows)

### Java

### C#

### JavaScript

### Python

### PHP

### HTTP

## Add multiple blank pages

Use `pageCount` to insert more than one blank page. The following example adds three A4 pages to the end of a document:

```json

{
  "parts": [
    {
      "file": "document"
    },
    {
      "page": "new",
      "pageCount": 3,
      "layout": {
        "size": "A4"
      }
    }
  ]
}

```

## Configure blank page layout

A new blank page part supports the same page layout options used by PDF generation. Set the page size, orientation, and margins with `layout`.

Use this instructions object to configure a blank page layout:

```json

{
  "parts": [
    {
      "file": "document"
    },
    {
      "page": "new",
      "pageCount": 1,
      "layout": {
        "size": "A4",
        "orientation": "landscape",
        "margin": {
          "top": 20,
          "right": 20,
          "bottom": 20,
          "left": 20
        }
      }
    }
  ]
}

```

## Delete pages

To delete pages, rebuild the output PDF from the page ranges you want to keep. The following example deletes page three from `document.pdf` by keeping pages zero through two, and then pages four through the end.

Use this instructions object to delete pages:

```json

{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 2
      }
    },
    {
      "file": "document",
      "pages": {
        "start": 4,
        "end": -1
      }
    }
  ]
}

```

Make sure the output keeps at least one page. A request that removes every page won’t produce a valid PDF.

## Duplicate a page

To duplicate a page, reference the same source file more than once. The following example prepends a duplicate of the first page before the full original document:

```json

{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 0
      }
    },
    {
      "file": "document"
    }
  ]
}

```

Use `-1` as both `start` and `end` to duplicate the last page.

## Reorder pages

The order of the `parts` array controls the page order in the output. The following example moves the last page to the front:

```json

{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": -1,
        "end": -1
      }
    },
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": -2
      }
    }
  ]
}

```

You can also combine page ranges from multiple PDFs to create a custom packet.

## Set page labels

Page labels control the page numbering shown by PDF viewers. They don’t change the physical page order or page count.

The following example sets labels for multiple page ranges:

```json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "pdf",
    "labels": [
      {
        "pages": {
          "start": 0,
          "end": 0
        },
        "label": "i"
      },
      {
        "pages": {
          "start": 1,
          "end": 3
        },
        "label": "intro"
      },
      {
        "pages": {
          "start": 4,
          "end": 5
        },
        "label": "final"
      }
    ]
  }
}

```

For page label examples, refer to the [set page label API task page](https://www.nutrient.io/api/set-page-label-api/).

## Manipulate pages from a URL

For remotely hosted source files, send a JSON request and pass the source URL in `parts[].file.url`. Use this instructions object:

```json

{
  "parts": [
    {
      "file": {
        "url": "https://example.com/document.pdf"
      },
      "pages": {
        "start": 0,
        "end": 0
      }
    },
    {
      "page": "new",
      "pageCount": 1,
      "layout": {
        "size": "Letter"
      }
    },
    {
      "file": {
        "url": "https://example.com/document.pdf"
      },
      "pages": {
        "start": 1,
        "end": -1
      }
    }
  ]
}

```

### Shell

Run this request to manipulate pages from a URL:

```bash

curl -X POST https://api.nutrient.io/build \
  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {
        "file": {
          "url": "https://example.com/document.pdf"
        },
        "pages": {
          "start": 0,
          "end": 0
        }
      },
      {
        "page": "new",
        "pageCount": 1,
        "layout": {
          "size": "Letter"
        }
      },
      {
        "file": {
          "url": "https://example.com/document.pdf"
        },
        "pages": {
          "start": 1,
          "end": -1
        }
      }
    ]
  }' \
  -o result.pdf

```

## Manipulate password-protected PDFs

If the source PDF is password-protected, include the password on every part that references the protected file. Use this instructions object:

```json

{
  "parts": [
    {
      "file": "protected_document",
      "password": "document-password",
      "pages": {
        "start": 0,
        "end": 0
      }
    },
    {
      "page": "new",
      "pageCount": 1,
      "layout": {
        "size": "Letter"
      }
    },
    {
      "file": "protected_document",
      "password": "document-password",
      "pages": {
        "start": 1,
        "end": -1
      }
    }
  ]
}

```

Nutrient DWS Processor API uses passwords only to open source documents for processing. To set a password on the output PDF, configure `output.user_password`, `output.owner_password`, and `output.user_permissions`.

## Combine page manipulation with other actions

The `/build` endpoint can manipulate pages and then apply additional actions. Actions run after Nutrient DWS Processor API assembles the `parts`.

The following example inserts a blank page, adds a watermark, and then linearizes the final PDF for web delivery:

```json

{
  "parts": [
    {
      "file": "document"
    },
    {
      "page": "new",
      "pageCount": 1,
      "layout": {
        "size": "Letter"
      }
    }
  ],
  "actions": [
    {
      "type": "watermark",
      "text": "APPENDIX",
      "width": "50%",
      "height": "20%",
      "opacity": 0.3,
      "rotation": 45
    }
  ],
  "output": {
    "type": "pdf",
    "optimize": {
      "linearize": true
    }
  }
}

```

For workflows that include cryptographic signing, complete all page manipulation before signing the final PDF.

## Reference

Page manipulation uses the Build API `parts` array. Use `FilePart` for existing PDF pages and `NewPagePart` for blank pages:

```typescript

type PageRange = {
  // First page to include. Defaults to `0`.
  // Page indexes are zero-based. Negative values count from the end.
  start?: number,

  // Last page to include. Defaults to `-1`, which means the last page.
  // The end value is inclusive.
  end?: number,
};

type FilePart = {
  // Multipart field name, or a remote URL object.
  file: string | { url: string },

  // Optional password for encrypted input PDFs.
  password?: string,

  // Optional page range to include from this input.
  pages?: PageRange,
};

type NewPagePart = {
  page: "new",

  // Number of blank pages to add. Defaults to `1`.
  pageCount?: number,

  layout?: {
    size?: "A4" | "Letter" | "Legal" | "A3" | "A5" | string,
    orientation?: "portrait" | "landscape",
    margin?: {
      top?: number,
      right?: number,
      bottom?: number,
      left?: number,
    },
  },
};

type BuildInstructions = {
  parts: Array<FilePart | NewPagePart>,
  actions?: BuildAction[],
  output?: {
    type?: "pdf",
  },
};

```

## Related API reference operations

- Refer to the [build document endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) API reference to add blank pages, delete pages by omission, duplicate page ranges, reorder pages, set page labels, and apply follow-up actions in a single request.

## Related guides

- Refer to the [PDF merge API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-merge-api.md) guide.

- Refer to the [PDF split API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-split-api.md) guide.

- Refer to the [PDF rotate API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-rotate-api.md) guide.

- Refer to the [PDF flatten API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-flatten-api.md) guide.

- Refer to the [PDF watermark API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-watermark-api.md) guide.

- Refer to the [PDF linearization API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-linearization-api.md) guide.

- Refer to the [tools and APIs](https://www.nutrient.io/guides/dws-processor/tools-and-api.md) guide.
---

## Related pages

- [Image-to-PDF API](/guides/dws-processor/tools-and-api/image-to-pdf-api.md)
- [Analyze Build API](/guides/dws-processor/tools-and-api/analyze-build-api.md)
- [Tools and APIs](/guides/dws-processor/tools-and-api.md)
- [Document-to-image API](/guides/dws-processor/tools-and-api/document-to-image-api.md)
- [Import Instant JSON API](/guides/dws-processor/tools-and-api/import-instant-json-api.md)
- [DOCX templating API](/guides/dws-processor/tools-and-api/docx-templating-api.md)
- [Import XFDF annotations API](/guides/dws-processor/tools-and-api/import-xfdf-annotations-api.md)
- [Office-to-PDF API](/guides/dws-processor/tools-and-api/office-to-pdf-api.md)
- [Markdown-to-PDF API](/guides/dws-processor/tools-and-api/markdown-to-pdf-api.md)
- [PDF digital signature API](/guides/dws-processor/tools-and-api/pdf-digital-signature-api.md)
- [PDF merge API](/guides/dws-processor/tools-and-api/pdf-merge-api.md)
- [PDF form filling API](/guides/dws-processor/tools-and-api/pdf-form-filling-api.md)
- [PDF flatten API](/guides/dws-processor/tools-and-api/pdf-flatten-api.md)
- [PDF OCR API](/guides/dws-processor/tools-and-api/pdf-ocr-api.md)
- [PDF generator API](/guides/dws-processor/tools-and-api/pdf-generator-api.md)
- [PDF linearization API](/guides/dws-processor/tools-and-api/pdf-linearization-api.md)
- [PDF rotate API](/guides/dws-processor/tools-and-api/pdf-rotate-api.md)
- [PDF optimization API](/guides/dws-processor/tools-and-api/pdf-optimization-api.md)
- [PDF security API](/guides/dws-processor/tools-and-api/pdf-security-api.md)
- [PDF split API](/guides/dws-processor/tools-and-api/pdf-split-api.md)
- [PDF-to-HTML API](/guides/dws-processor/tools-and-api/pdf-to-html-api.md)
- [PDF-to-image API](/guides/dws-processor/tools-and-api/pdf-to-image-api.md)
- [PDF-to-Markdown API](/guides/dws-processor/tools-and-api/pdf-to-markdown-api.md)
- [PDF-to-Office API](/guides/dws-processor/tools-and-api/pdf-to-office-api.md)
- [PDF-to-PDF/A API](/guides/dws-processor/tools-and-api/pdf-to-pdfa-api.md)
- [PDF watermark API](/guides/dws-processor/tools-and-api/pdf-watermark-api.md)
- [Redaction API](/guides/dws-processor/tools-and-api/redaction-api.md)
- [PDF/UA auto-tagging API](/guides/dws-processor/tools-and-api/pdfua-api.md)