Add Pages to PDFs

Document Engine lets you add new pages to a document by sending a multipart request to the /api/build endpoint and attaching the input file(s) and the instructions JSON. This guide provides some examples of adding new pages to PDFs.

Before you get started, make sure Document Engine is up and running.

You’ll be sending multipart POST requests with instructions to Document Engine’s /api/build endpoint. To learn more about multipart requests, refer to our blog post on the topic, A Brief Tour of Multipart Requests.

Check out the API Reference to learn more about the /api/build endpoint and all the actions you can perform on PDFs with Document Engine.

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:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API 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
POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="document"; filename="example-document.pdf"
Content-Type: application/pdf

<PDF data>
--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, 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 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:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API 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
POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="document"; filename="example-document.pdf"
Content-Type: application/pdf

<PDF data>
--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:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API 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
POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API 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--