Inkspan › Guides › How to split a PDF into pages in Node.js

How to split a PDF into pages in Node.js

Q: What is the ZIP structure?

A flat archive with no directories — page_1.pdf, page_2.pdf, and so on, in document order.

The /v1/pdf/split endpoint explodes a PDF into one file per page and returns them as a ZIP archive named pages.zip, containing page_1.pdf, page_2.pdf, and so on. This matters for pipelines that process documents a page at a time — per-page OCR, routing scanned batches, or extracting a signature page from a contract.

Note the response is a ZIP, not a PDF. This is the detail most often missed when wiring the endpoint up for the first time, because every other manipulation endpoint returns a PDF.

Also in: cURL · Python

Node.js example

import fs from 'node:fs';

const fd = new FormData();
fd.append('file', new Blob([fs.readFileSync('input.pdf')]), 'input.pdf');

const res = await fetch('https://api.inkspan.dev/v1/pdf/split', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.INKSPAN_KEY },
  body: fd,
});
if (!res.ok) throw new Error(await res.text());
fs.writeFileSync('pages.zip', Buffer.from(await res.arrayBuffer()));

Request parameters

Name	Type	Required	Description
`file`	file	yes	The PDF to split. One output file is produced per page.

Response

Returns a ZIP archive as a binary stream with Content-Type: application/zip and Content-Disposition: attachment; filename=pages.zip. Write the response body straight to disk — do not parse it as JSON.

Things that catch people out

The response is application/zip, not a PDF. Writing it to a .pdf file produces something no reader will open.
Page files are named page_1.pdf upward and are 1-indexed, which is worth noting if your own code is 0-indexed.
Every page becomes a file. A 500-page document yields a 500-entry archive, so stream the response rather than buffering it in memory.
There is no page-range parameter. To take a subset, split and then keep the entries you want.

Errors

Status	Meaning	Fix
`401`	Invalid or missing API key	Send your key in the `X-API-Key` header.
`402`	Monthly quota exceeded	The response reports used/quota. Upgrade at inkspan.dev/#pricing.
`422`	Missing or invalid parameter	Check required fields in the table above — the body names the offending field.

Failed requests do not count against your quota; only successful ones are metered.

Frequently asked questions

Can I split on a range instead of every page?

Not directly. Split into pages and select the entries you need from the archive, or merge the ones you want back together.

What is the ZIP structure?

A flat archive with no directories — page_1.pdf, page_2.pdf, and so on, in document order.

Does this count as one document?

Yes. Quota is metered per request, not per page produced.

Get a free API key →

Related Manipulate guides: merge PDF files · compress a PDF · add a watermark to a PDF · convert a PDF to images · fill a PDF form