How many PDF operations does the MostlyPDF API support?

35, all behind a single POST /v1/process endpoint. You select one with the "tool" field; there is no separate URL per operation.

How do I authenticate with the MostlyPDF API?

Send your sk_ key as a bearer token: Authorization: Bearer sk_your_key. The x-api-key header is accepted as an alternative.

How are files sent to and returned from the API?

Base64. Input files go in the "files" array; results come back base64-encoded in "outputs". Multi-file operations such as merge-pdf accept several inputs in one call.

How is the MostlyPDF API priced?

Flat and metered: one billable operation per call, whichever tool you run. There is no per-operation credit weighting.

MostlyPDF API reference

35 PDF operations behind one endpoint. Send base64 files, name a tool, get base64 files back. One billable operation per call — no per-operation credit weighting, no separate URL to learn per tool.

EndpointPOST /v1/process

AuthBearer sk_ key

Operations35

PricingFlat metered, 1 op per call

Authentication

Every request carries your secret key as a bearer token. Keys start with sk_ and are created in your dashboard. The x-api-key header is accepted as an alternative for clients that cannot set Authorization.

Authorization: Bearer sk_live_your_key

API keys come with the Pro plan. GET /v1/process with your key returns { "ok": true, "scopes": [...] } — a free way to test a key without running or billing anything.

Pricing, limits and retries

Pricing. Every successful call is one operation, whichever tool you run: $1 per 100 operations, charged from your Mostly Tiny wallet. No card or an empty wallet returns 402 with a billing_url.

Rate limits. Keys billed from a funded wallet have no per-key request cap; throughput is bounded by concurrency (about 20 requests in flight). Callers on the free trial allowance get 60 requests a minute plus a small daily cap per conversion tool. Over a limit: 429, code: "quota", a resetAt timestamp and a Retry-After header.

Retries. Operations are pure transforms — nothing is stored and nothing on your account changes — so any failed call is safe to retry. Send an Idempotency-Key header and a retry with the same key is not charged twice.

Use it from an AI agent

The Mostly Tiny MCP server exposes this API as tools for Claude, ChatGPT and other MCP clients. Sign in with OAuth; no key to paste:

claude mcp add --transport http mostly-tiny https://mcp.mostlytiny.io

Machine-readable entry points: the OpenAPI 3.1 document, the API catalog (RFC 9727) and llms.txt.

The request

One POST to https://mostly-pdf.web.app/v1/process with a JSON body of three fields:

Field	Type	Required	What it is
`tool`	string	yes	Which operation to run — any `slug` from the table below.
`files`	string[]	yes	Input file(s), base64-encoded. Multi-file operations take several.
`options`	object	no	Operation-specific settings, e.g. `{"degrees":90}` or `{"ranges":["1-3","5"]}`.

The response returns outputs: an array of base64 result files, in the same order the operation produces them.

curl

curl -X POST https://mostly-pdf.web.app/v1/process \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "merge-pdf",
    "files": ["<base64 of first.pdf>", "<base64 of second.pdf>"]
  }'

JavaScript (Node)

const res = await fetch("https://mostly-pdf.web.app/v1/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MOSTLYPDF_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tool: "rotate-pdf",
    options: { degrees: 90 },
    files: [Buffer.from(await fs.readFile("in.pdf")).toString("base64")],
  }),
});
const { outputs } = await res.json();
await fs.writeFile("out.pdf", Buffer.from(outputs[0], "base64"));

Python

import base64, os, requests

with open("in.pdf", "rb") as f:
    payload = base64.b64encode(f.read()).decode()

r = requests.post(
    "https://mostly-pdf.web.app/v1/process",
    headers={"Authorization": f"Bearer {os.environ['MOSTLYPDF_KEY']}"},
    json={"tool": "compress-pdf", "files": [payload]},
    timeout=120,
)
r.raise_for_status()
with open("out.pdf", "wb") as f:
    f.write(base64.b64decode(r.json()["outputs"][0]))

All 35 operations

Pass any slug below as the tool field. Free operations run without a paid plan; where a daily free allowance applies it is listed. Operations marked conversion service run server-side and are the ones that return 501 if that service is not enabled on your account.

slug	Operation	Input files	Options (* required)	Tier	Free allowance	Runs on
`chat-with-pdf`	Chat with PDF	one file	—	Pro	unlimited	app only — not on /v1/process
`compare-pdf`	Compare PDF	two or more	none	Free	unlimited	conversion service
`compress-pdf`	Compress PDF	one file	`quality`	Free	unlimited	conversion service
`crop-pdf`	Crop PDF	one file	`top` `bottom` `left` `right` `pages`	Free	unlimited	in-browser engine
`email-to-pdf`	Email to PDF	none — content in options	`html`* `paper`	Free	unlimited	render engine
`excel-to-pdf`	Excel to PDF	one file	`ext`	Free	unlimited	conversion service
`extract-pages`	Extract Pages	one file	`pages`*	Free	unlimited	in-browser engine
`fill-pdf-form`	Fill PDF Form	one file	`fields`* `flatten`	Free	unlimited	in-browser engine
`html-to-pdf`	HTML to PDF	none — content in options	`html`* `paper`	Free	unlimited	render engine
`jpg-to-pdf`	JPG to PDF	two or more	`margin` `pageSize`	Free	unlimited	in-browser engine
`markdown-to-pdf`	Markdown to PDF	none — content in options	`html`* `paper`	Free	unlimited	render engine
`merge-pdf`	Merge PDF	two or more	none	Free	unlimited	in-browser engine
`ocr-pdf`	OCR PDF	one file	`lang` `force`	Pro	unlimited	conversion service
`odt-to-pdf`	ODT to PDF	one file	none	Free	unlimited	conversion service
`organize-pdf`	Organize PDF	one file	`order`*	Free	unlimited	in-browser engine
`page-numbers`	Add Page Numbers	one file	`position` `start` `fontSize` `margin`	Free	unlimited	in-browser engine
`pdf-to-excel`	PDF to Excel	one file	none	Pro	unlimited	conversion service
`pdf-to-jpg`	PDF to JPG	one file	`dpi` `quality`	Free	unlimited	conversion service
`pdf-to-pdfa`	PDF to PDF/A	one file	none	Free	unlimited	conversion service
`pdf-to-powerpoint`	PDF to PowerPoint	one file	none	Pro	unlimited	conversion service
`pdf-to-word`	PDF to Word	one file	none	Pro	unlimited	conversion service
`powerpoint-to-pdf`	PowerPoint to PDF	one file	`ext`	Free	unlimited	conversion service
`protect-pdf`	Protect PDF	one file	`password`* `ownerPassword`	Free	unlimited	conversion service
`redact-pdf`	Redact PDF	one file	`boxes`* `dpi`	Pro	unlimited	conversion service
`remove-pages`	Remove Pages	one file	`pages`*	Free	unlimited	in-browser engine
`repair-pdf`	Repair PDF	one file	none	Free	unlimited	conversion service
`request-signature`	Request Signature	one file	—	Pro	one free envelope every month with a Mostly Tiny account/day	app only — not on /v1/process
`rotate-pdf`	Rotate PDF	one file	`degrees` `pages`	Free	unlimited	in-browser engine
`rtf-to-pdf`	RTF to PDF	one file	none	Free	unlimited	conversion service
`sign-pdf`	Sign PDF	one file	`type` `text` `image` `page` `x` `y` `width` `height` `fontSize` `dated` `flatten`	Pro	unlimited	in-browser engine
`sign-pdf-certified`	Certify PDF (digital signature)	one file	`p12`* `passphrase` `reason` `location` `name` `contactInfo`	Pro	unlimited	in-browser engine
`split-pdf`	Split PDF	one file	`ranges` `everyN`	Free	unlimited	in-browser engine
`summarize-pdf`	Summarize PDF	one file	—	Pro	unlimited	app only — not on /v1/process
`txt-to-pdf`	TXT to PDF	one file	none	Free	unlimited	conversion service
`unlock-pdf`	Unlock PDF	one file	`password`*	Free	unlimited	conversion service
`url-to-pdf`	Webpage to PDF	none — content in options	`url`* `paper`	Free	unlimited	render engine
`watermark-pdf`	Watermark PDF	one file	`text`* `opacity` `fontSize` `color`	Free	unlimited	in-browser engine
`word-to-pdf`	Word to PDF	one file	`ext`	Free	unlimited	conversion service

Errors

Errors return a JSON body with a machine-readable error field and an HTTP status:

Status	Meaning
`200`	Processed. File tools return `FileResult`; render tools return `HostedPdfResult`.
`400`	Invalid argument — unknown tool, no files, or options the tool rejects.
`401`	Missing or invalid API key.
`402`	Payment required — no card on file (`needs_card`) or the wallet is too low (`insufficient_balance`). Follow `billing_url`.
`403`	The key lacks the `pdf:run` scope.
`413`	Input too large for the request.
`422`	The input is valid JSON but the operation cannot apply to this file — e.g. crop margins larger than the page (`over-crop`) or no matching form fields (`no-fields-matched`).
`429`	Rate limit or trial allowance reached. Keys billed from a funded wallet have no per-key request cap; throughput is bounded by concurrency (requests over ~20 in flight queue briefly). Callers on the free trial allowance (a Mostly Tiny identity with no card on file, e.g. via the MCP) get 60 requests/minute plus a small daily cap per conversion tool (5–20/day). Over a limit you get `429` with `code: "quota"`, a `resetAt` timestamp and a `Retry-After` header.
`500`	Unexpected failure. Safe to retry.
`501`	The tool needs the conversion service, which is not enabled on this deployment.
`502`	The wallet could not be charged (billing service error). Retry with the same Idempotency-Key.
`503`	A downstream engine is temporarily unavailable. Retry with backoff.

Try it

The interactive explorer below is generated from the same OpenAPI document that powers this page — you can also point your own client or an MCP server straight at it.

A Mostly Tiny product · all PDF tools