Most applications do not need to explode a document into dozens of one-page files. They need a useful subset: the first three pages of a report, selected exhibits from a case file, or one section of a handbook. The split endpoint extracts exactly those pages into a new PDF.

The endpoint and page syntax

Send a PDF and a pages string to POST /v1/split. Page numbers are 1-indexed, so the first page is 1, not 0. A page spec can contain individual pages, inclusive ranges, or both.

4 extracts page 4.
2-6 extracts pages 2 through 6.
1-3,8,11-13 combines ranges and a single page.

The response is one PDF containing the requested pages. This endpoint does not return a ZIP or a separate file for each page.

Authenticate the request

Generate an API key at app.filealloy.com, store it outside your code, and include it in the X-API-Key header. The request body is multipart form data.

Extract pages with curl

The following command keeps pages 1 through 3, page 8, and pages 11 through 13:

curl -X POST https://api.filealloy.com/v1/split \
  -H "X-API-Key: ${FILEALLOY_API_KEY}" \
  -F "[email protected]" \
  -F "pages=1-3,8,11-13" \
  -o selected-pages.pdf

The pages field is text even though it contains numbers. Quoting it also prevents the shell from treating punctuation specially.

Extract pages in Python

Use files for the PDF and data for the page spec. Check the status before writing the returned bytes.

from pathlib import Path
import requests

source = Path("handbook.pdf")
with source.open("rb") as pdf:
    response = requests.post(
        "https://api.filealloy.com/v1/split",
        headers={"X-API-Key": "fa_live_your_key"},
        files={"file": (source.name, pdf, "application/pdf")},
        data={"pages": "1-3,8,11-13"},
        timeout=60,
    )

if not response.ok:
    try:
        detail = response.json()["error"]["message"]
    except (ValueError, KeyError, TypeError):
        detail = response.text or "Unknown API error"
    raise RuntimeError(f"Split failed ({response.status_code}): {detail}")

Path("selected-pages.pdf").write_bytes(response.content)
print("Saved selected-pages.pdf")

Extract pages in Node.js

With Node.js 18 or newer, the multipart request needs no third-party HTTP package. Do not set a Content-Type header manually because fetch adds the required boundary.

import { readFile, writeFile } from "node:fs/promises";

const input = await readFile("handbook.pdf");
const form = new FormData();
form.append("file", new Blob([input], { type: "application/pdf" }), "handbook.pdf");
form.append("pages", "1-3,8,11-13");

const response = await fetch("https://api.filealloy.com/v1/split", {
  method: "POST",
  headers: { "X-API-Key": "fa_live_your_key" },
  body: form,
});

if (!response.ok) {
  const body = await response.json().catch(() => null);
  const message = body?.error?.message ?? response.statusText;
  throw new Error(`Split failed (${response.status}): ${message}`);
}

const pdf = Buffer.from(await response.arrayBuffer());
await writeFile("selected-pages.pdf", pdf);
console.log(`Saved selected-pages.pdf (${pdf.length} bytes)`);

Validate page selections in your application

Page specs usually come from a user, so validate the shape before sending them. Accept positive integers, commas, and ranges with a lower and upper bound. Reject empty selections, page zero, negative values, and reversed ranges such as 8-3. If your application already knows the source page count, reject out-of-range selections early and show a more useful message.

Keep the page spec alongside the output record. It gives you a compact audit trail and makes the extraction reproducible if the job needs to run again.

Errors to expect

A missing or invalid page spec can produce 400. Oversized uploads return 413, non-PDF input returns 415, and a document that cannot be processed returns 422. If the service returns 503, use the Retry-After header to schedule a later attempt. Monthly quota exhaustion returns 429.

The API sends errors as JSON with error.code and error.message. Both code examples read that message and avoid writing the response as a PDF when the status is not successful.

Split versus remove pages

Use split when you can describe what you want to keep. Use remove pages when it is easier to name the small set you want to discard. For example, extracting 1-40 from a 42-page file and removing 41-42 can produce the same shape, but the second request better expresses the intent.

Try a real page range

Test against a document with visible page numbers so the selection is easy to verify. Create a key at app.filealloy.com, send one page range, and inspect the returned PDF before wiring the call into a larger workflow.