Bytefusedocs
Subscribe

Pages

Page Numbers

Stamp page numbers onto a PDF — choose the position, the starting number, the first page to number (to skip a cover), and a format like “Page 3 of 40”.

Free to try — no key required 10 credits / callSynchronous

Overview

Unlike the other page tools, this one returns a JSON body with a download URL (not a streamed file). On the free-try path.

POSThttps://api.bytefuse.in/api/v1/pdf/page-numbers

Request

Content type multipart/form-data:

filefilerequired
The PDF to number. A non-PDF returns 415.
positionstringoptional
Where to place the number — e.g. bottom-center, bottom-left, top-right, center.Default: bottom-center
startintoptional
The number shown on the first numbered page.Default: 1
font_sizeintoptional
Point size of the stamped number.Default: 11
fmtstringoptional
The format string — see the tokens below, e.g. Page {n} of {total}.Default: {n}
first_pageintoptional
The 1-based page on which numbering begins — set it higher to skip a cover or title page.Default: 1
colorstringoptional
A hex color for the number.Default: #000000

Format tokens

Compose fmt from these tokens:

{n}Arabic page number — 1, 2, 3
{roman} / {ROMAN}Roman numerals — i, ii / I, II
{alpha} / {ALPHA}Letters — a, b / A, B
{total}Total number of numbered pages

Response

200 OK, application/json:

200 OK
{
  "success": true,
  "url": "https://<r2-host>/pdf/<date>/<uuid>.pdf",
  "credits_charged": 1
}

Download URL

url is a public R2 link (permanent under the default config); no expires_at is returned. The X-Credits-Charged header mirrors credits_charged (0 anonymous).

Examples

curl -X POST https://api.bytefuse.in/api/v1/pdf/page-numbers \
  -F "file=@report.pdf" \
  -F "position=bottom-center" \
  -F "fmt=Page {n} of {total}" \
  -F "first_page=2" \
  -F "start=1"

Errors

415The uploaded file isn’t a PDF.
422An invalid parameter value.
402 / 429 / 503Insufficient credits, rate limited, or capacity/config error.
500The operation failed unexpectedly.
PreviousReorder PagesNext Crop PDF