---
name: "pdf123-add-page-numbers"
description: "Insert page numbers into a PDF. Runs the PDF123 \"Add Page Numbers\" tool (pdf123.xyz) over its REST API with curl, no account needed. Use when the user wants this done to their file. Also known as: 添加页码, Añadir números de página, पृष्ठ संख्या लगाएँ, إضافة أرقام الصفحات, Adicionar números de página, Tambah nomor halaman, Ajouter des numéros de page, Номера страниц, ページ番号の追加, Seitenzahlen einfügen, 페이지 번호 넣기, Thêm số trang, Sayfa numarası ekle, 加入頁碼, Aggiungi numeri di pagina, ใส่เลขหน้า, Numeruj strony, Номери сторінок, Paginanummers toevoegen, Tambah nombor halaman, Lägg till sidnummer, Προσθήκη αριθμών σελίδας, Номерация, Afegeix números de pàgina, Weka namba za ukurasa."
compatibility: "Needs curl 7.76+ and outbound HTTPS to pdf123.xyz, or PDFX_API_BASE pointing at a self-hosted pdfx-server."
---

# Add Page Numbers (PDF123)

Insert page numbers into a PDF.

Web version: https://pdf123.xyz/add-page-numbers · All tools: https://pdf123.xyz/skills/pdf123.md

## When to use

- Number a merged exhibit binder
- Continue a sequence across volumes with a non-1 starting number
- Give a print packet numbers reviewers can cite

## Run it

Replace the sample file names and values with the user's, then run:

```bash
API="${PDFX_API_BASE:-https://pdf123.xyz}"
curl -sS --fail-with-body -X POST "$API/api/v1/misc/add-page-numbers" \
  -F "fileInput=@input.pdf" \
  -F "fontSize=12" \
  -F "position=8" \
  -F "startingNumber=1" \
  --output-dir "pdf123-output/$(date +%Y%m%d-%H%M%S)" --create-dirs -OJ -w '%{filename_effective} %{content_type}\n'
```

## Inputs

Everything is `multipart/form-data`. The command above already sends each field with its default; keep them all and change only the values the user asked for, since some endpoints reject a missing optional field.

| Field | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `fileInput` | file | yes | | .pdf (one file) |
| `fontSize` | number | no | `12` | Font size |
| `position` | choice | no | `8` | Position. One of: `1` (Top left), `2` (Top center), `3` (Top right), `7` (Bottom left), `8` (Bottom center), `9` (Bottom right) |
| `startingNumber` | text | no | `1` | Starting number |

## Result

curl saves the result in a new `pdf123-output/<timestamp>/` directory under the server's file name and prints its path and content type. Several output files come back as one ZIP. Tell the user where the file is.

## Limits

- May overlap existing printed numbers
- Always Helvetica; no font choice
- Does not rewrite PDF page-label dictionaries
- Upload limit on this website: 500 MB per file, sent in chunks above about 95 MB. A single direct API request body is capped at 100 MB.

## Errors

- A non-zero curl exit means the request failed. The saved file then holds `application/problem+json`; read it and report its `detail` to the user instead of retrying blindly.
- `413`: the upload exceeds 100 MiB. `429`: wait for `Retry-After` seconds, then retry once.
- Send `X-API-KEY: $PDFX_API_KEY` only if the user has a PDF123 API key; anonymous calls work without it.

## Privacy

Files are uploaded to the API host, processed, and deleted once the response is sent. For confidential files, ask before uploading, or use a self-hosted server via `PDFX_API_BASE`.