Insert a blank PDF page at any position

Provide the PDF and a one-based position, and the tool places a clean page there using the same dimensions as the page at that location. To add a page at the end, use the position immediately after the current last page. The operation is deterministic, keeps the original page order, and clearly rejects positions that do not exist.

Choose the exact insertion position

Positions are one-based because they describe where the new page will appear to a person reading the finished document. Position 1 inserts a blank page before the current first page. Position 2 places it between the current first and second pages. For a document with five pages, position 6 appends a blank page after page five. Those are the only valid positions: the lowest is 1 and the highest is the existing page count plus one. This explicit rule prevents an ambiguous request from silently producing a document with the page in the wrong place. If the position is zero, negative, fractional, or larger than the append position, the request returns an invalid-input error and leaves the source unchanged. Before automating a workflow, count the source pages and calculate the position from the document state you actually submit. That matters when an earlier step can add, remove, or split pages. The result reports the inserted position and new total, making it straightforward to verify the transformation before storing or forwarding the PDF.

How the blank page gets its size

The inserted page uses the effective media box of the page currently at the requested position. That means inserting before a portrait letter page creates a portrait letter blank, while inserting before a landscape or custom-size page preserves those dimensions. When the requested position appends to the document, there is no following page to inspect, so the new page copies the size of the existing last page. This behavior is particularly useful in mixed-size PDFs such as scanned records, presentation handouts, architectural packets, and combined reports. The page is intentionally blank: it has an empty resource dictionary and no content stream, annotations, form fields, or copied marks. Only the page geometry is carried over. The response also includes the computed width and height in PDF points, so a caller can confirm which dimensions were selected. A PDF point is one seventy-second of an inch. The source pages retain their order and content; the operation changes the page tree only as needed to introduce the new blank page.

Prepare compatible input and verify the result

Supply a classic PDF either as plain PDF text or as a PDF base64 data URI. The current beta implementation deliberately rejects cross-reference-stream documents instead of guessing at structures it cannot safely reconstruct. This boundary keeps the algorithm deterministic and makes failures visible. The parser reads the catalog and page tree, follows nested page nodes, resolves inherited media boxes, inserts a new page reference into the correct parent, updates every affected page count, and rebuilds a valid classic cross-reference table. No network request, clock, random value, storage service, or model is involved. After processing, check the returned page count, insertion position, width, and height, then save or pass along the returned PDF. For production automation, test representative source files first, especially documents generated by unusual publishing software. If a file is rejected as an unsupported cross-reference stream, convert it to a classic PDF with a trusted PDF utility before retrying. Each API request costs $0.002; the same deterministic operation can also power an interactive browser workflow.