POST /api/merge

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

const cover    = await readFile('cover.pdf');
const body     = await readFile('body.pdf');
const appendix = await readFile('appendix.pdf');

const fd = new FormData();
// Order matters — pages concatenate in field order, not filename order.
fd.append('pdf', new Blob([cover],    { type: 'application/pdf' }), 'cover.pdf');
fd.append('pdf', new Blob([body],     { type: 'application/pdf' }), 'body.pdf');
fd.append('pdf', new Blob([appendix], { type: 'application/pdf' }), 'appendix.pdf');

const res = await fetch('https://pdfops.dev/api/merge', { method: 'POST', body: fd });
if (!res.ok) {
  const err = await res.json();
  throw new Error(`PDFops merge failed: ${err.error} — ${err.details}`);
}
await writeFile('combined.pdf', Buffer.from(await res.arrayBuffer()));

import httpx

# httpx accepts a list of (fieldname, file-tuple) pairs for repeated fields.
files = [
    ('pdf', ('cover.pdf',    open('cover.pdf', 'rb'),    'application/pdf')),
    ('pdf', ('body.pdf',     open('body.pdf', 'rb'),     'application/pdf')),
    ('pdf', ('appendix.pdf', open('appendix.pdf', 'rb'), 'application/pdf')),
]

r = httpx.post('https://pdfops.dev/api/merge', files=files, timeout=30)
if r.status_code != 200:
    err = r.json()
    raise RuntimeError(f"PDFops merge failed: {err['error']} — {err['details']}")

with open('combined.pdf', 'wb') as f:
    f.write(r.content)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func merge(paths []string, out string) error {
    var body bytes.Buffer
    w := multipart.NewWriter(&body)

    // Order matters: pages concatenate in the order the fields are written.
    for _, p := range paths {
        data, err := os.ReadFile(p)
        if err != nil {
            return err
        }
        part, err := w.CreateFormFile("pdf", p)
        if err != nil {
            return err
        }
        if _, err := part.Write(data); err != nil {
            return err
        }
    }
    w.Close()

    req, err := http.NewRequest("POST", "https://pdfops.dev/api/merge", &body)
    if err != nil {
        return err
    }
    req.Header.Set("Content-Type", w.FormDataContentType())

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    if resp.StatusCode != 200 {
        var apiErr struct {
            Error   string `json:"error"`
            Details string `json:"details"`
        }
        json.NewDecoder(resp.Body).Decode(&apiErr)
        return fmt.Errorf("merge failed: %s — %s", apiErr.Error, apiErr.Details)
    }

    f, err := os.Create(out)
    if err != nil {
        return err
    }
    defer f.Close()
    _, err = io.Copy(f, resp.Body)
    return err
}

No hard cap in code, but the multipart body has to fit in ~10 MB total. For typical 1-2 MB inputs, 5-10 per request is comfortable. For larger merges, chain multiple /api/merge calls.

The same order as the multipart fields in the request body. All pages of each input are preserved in their original order within that input.

Page-level content yes, document-level AcroForm metadata no. Fill form PDFs via /api/fill-form first, then merge the filled outputs.

If you have one PDF there's nothing to merge — return it unchanged on your side. The minimum-of-2 check surfaces misuse loudly rather than wasting a call.

Not supported. Decrypt server-side first (qpdf, pdftk).

You sent fewer than 2 pdf multipart fields. The endpoint refuses a 1-input request because there's nothing to merge — return the one PDF unchanged on your side. If you're getting insufficient_pdfs on a call you thought had multiple inputs: check that all field names are pdf exactly (not pdfs or file); some HTTP clients silently rename multipart parts on conflict. Also check that you're not accidentally sending the same buffer twice with one field name — some FormData libraries dedupe by name unless explicitly told to repeat.

One of the input PDFs couldn't be parsed by pdf-lib. The details field identifies which input index failed (0-based). Common causes: the file isn't actually a PDF (check the first 4 bytes — should be %PDF); the PDF is encrypted (decrypt server-side first via qpdf or pdftk); the PDF is corrupt or truncated (re-read from source); the PDF uses a feature pdf-lib doesn't support yet (rare, but PDF 2.0 with object-streams + encryption can trip it). Debug: try opening the file locally in Acrobat or Preview — if those can read it, it's a pdf-lib quirk worth filing via the waitlist form's message field.

pdf-lib's save() threw after the merge succeeded structurally. Rare; usually indicates corruption that surfaced during serialization (e.g., a cross-reference table entry that pointed at deleted-during-merge content). Retryable — the next call may succeed if the failure was edge-case timing. If the same merge fails twice in a row with save_failed, one of the input PDFs is the likely root cause; try removing each input one at a time to isolate.