Skip to main content
PPDF123

PDF123 for developers: REST API, SDK, command line and MCP

The PDF123 developer platform exposes the same 97 PDF tools through four interfaces: a REST API described by OpenAPI, a TypeScript SDK, the pdfx command line and MCP servers for AI agents. Anonymous calls need no account or API key.

On this page

Which way should I use PDF123 from code?

All four interfaces call the same operations, so a merge gives the same result in each. Pick by where your code runs.

InterfaceBest forInstall or addressGuide
REST APIAny language, servers, shell scriptshttps://pdf123.xyz/api/v1API reference
TypeScript SDKNode, Bun and browser code that needs typesnpm install @pdf123/sdkSDK guide
Command lineTerminals, CI jobs, batches of local filesnpm install -g @pdf123/cliCLI guide
MCPAI agents such as Claude Code, Claude Desktop and Cursornpx -y @pdf123/mcp or https://pdf123.xyz/mcpMCP guide

Use the REST API if your code is not written in TypeScript. Use the SDK if it is, because tool options are typed and checked before upload. Use the command line for one-off jobs and shell scripts. Use MCP when an AI agent should decide which tool to run.

The catalog has 97 tools. 58 of them have a page on this website, such as Merge PDF, Split PDF and Compress PDF. The others are backend operations without a web page, and all are available in the SDK, the command line and MCP.

How do I run my first request?

Merge two files with curl. The request is a multipart form with one fileInput part per file.

REST: merge two PDFsbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

The same merge with the TypeScript SDK:

SDK: merge two PDFsts
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });

The same merge with the command line:

CLI: merge two PDFsbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

How does authentication work?

Anonymous calls to the public API need no account and no key. Send an API key in the X-API-KEY header when you want to identify your traffic or call the hosted MCP endpoint, which always requires a key.

Sign in to create a key in the panel below, and store it somewhere safe.

Checking your session...

Call the API with a keybash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -H "X-API-KEY: <your-key>" \
  -F [email protected] -F [email protected] -o merged.pdf

The SDK takes the key as apiKey. The command line and the local MCP server read it from the PDFX_API_KEY environment variable.

Note

On a self-hosted server, set the SECURITY_CUSTOMGLOBALAPIKEY environment variable to define one key that the server accepts. See Self-host.

Where is the API reference?

The REST API is documented in two forms. Swagger UI lets you try each endpoint in the browser. The OpenAPI document is the machine-readable source for client generators.

Every operation is a POST under the base URL https://pdf123.xyz/api/v1, grouped by category. For example, merge is /general/merge-pdfs and compress is /misc/compress-pdf.

How do I chain several tools in one request?

POST /api/v1/pipeline takes the fileInput parts and a steps field. The steps field is a JSON array of objects with an op and optional params. Each step receives the output of the previous step.

Merge, then compress, in one requestbash
curl -X POST https://pdf123.xyz/api/v1/pipeline \
  -F [email protected] -F [email protected] \
  -F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
  -o out.pdf

How do I retry a request safely?

Send an Idempotency-Key header on any operation. A repeat of the same request within 24 hours returns the first result with the header Idempotency-Replayed: true instead of running again. Using the same key for a different request is rejected. Results larger than 32 MiB are not stored, so a repeat of such a request answers 409 and needs a new key.

What are the size and rate limits?

LimitValue
File size on the website500 MB per file
One direct API request body100 MiB, multipart framing included
Chunked uploadThe SDK switches to the upload API automatically above 95 MB in total

Responses carry the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A response with status 429 adds Retry-After. Read the headers instead of assuming a fixed quota, because a self-hosted server sets its own limits. The blog post on the request size limit explains the error you get for an oversized body.

What does an error look like?

Failures return application/problem+json with the fields type, title, status, detail, code, reason and hint. Branch on reason and fall back to code. The detail text is written for people and never contains raw tool output. All codes are listed on Error codes.

Code or reasonHTTP statusMeaning
bad_request400Invalid parameters or multipart body
password_required400The PDF is encrypted and no password was sent
invalid_pdf400The file is not a PDF or is damaged; try Repair PDF
page_out_of_range400A requested page does not exist
not_found404Unknown operation path
rate_limited429Quota used up; wait for Retry-After

Which tools can I call first?

These twelve tools cover most requests. Use the tool page to try a tool in the browser, and see Recipes for copy-and-run examples of common jobs in curl, pdfx and Node.

Tool pageAPI endpointCLI commandWhat it does
Merge/general/merge-pdfspdfx mergeCombine several PDFs into one
Split/general/split-pagespdfx splitDivide a PDF into separate files
Compress/misc/compress-pdfpdfx compressRecompress PDF streams to reduce size
Rotate/general/rotate-pdfpdfx rotateChange page orientation
Protect/security/add-passwordpdfx protectEncrypt a PDF with a password
Unlock/security/remove-passwordpdfx unlockRemove password protection
Watermark/security/add-watermarkpdfx watermarkAdd a text or image watermark
OCR/misc/ocr-pdfpdfx ocrRead a scanned PDF and return Markdown
PDF to Markdown/convert/pdf/markdownpdfx pdf-to-markdownConvert a PDF into Markdown
PDF to Word/convert/pdf/wordpdfx convert-to-wordConvert a PDF into an editable Word file
Document info/security/get-info-on-pdfpdfx get-infoReport metadata, permissions, fonts and structure
Repair/misc/repairpdfx repairRebuild the structure of a damaged PDF

Endpoints are relative to https://pdf123.xyz/api/v1. Run pdfx list or open the OpenAPI document to see all 97 tools.

How do I use PDF123 from an AI agent?

An agent can use the tools in three ways:

  • Connect an MCP server. The MCP guide covers the local @pdf123/mcp server for files on your machine and the hosted endpoint at https://pdf123.xyz/mcp.
  • Load an agent skill. Agent skills are SKILL.md files for Claude Code, Codex, Cursor and similar tools, one for the catalog and one for each tool.
  • Read the site index. /llms.txt lists the tools, the API and the MCP endpoint in plain text, and /site.jsonld describes the site as structured data.

The blog post "Built for AI Agents, Not Just Browsers" on the PDF123 blog explains how the REST API and MCP fit together.

Can I run PDF123 on my own server?

Yes. The backend is the pdfx-server program, which runs in Docker. Point the SDK, the command line or the MCP server at it with PDFX_API_BASE, and your files stay on your network. See Self-host for setup and Enterprise for support options.

FAQ

Is the PDF123 API free?

Yes for anonymous use. Calls to the public API do not need an account or a key. Hosted responses include rate-limit headers, so a client can slow down before it receives a 429 response.

Do I need an API key?

No for the REST API, the SDK and the command line when you use the public site. Yes for the hosted MCP endpoint at /mcp, which answers 401 without an X-API-KEY header. You can create a key on this page after signing in.

What is the file size limit?

The website accepts files up to 500 MB each. A single direct API request body may be up to 100 MiB including multipart framing. The SDK uploads larger inputs in chunks automatically once the total passes 95 MB.

Can I self-host the API?

Yes. Run the server yourself and set the API base to its address. The SDK, the command line and the local MCP server all accept a custom base URL.

How do I report an error?

Copy the code, reason and detail fields from the problem response, plus the time of the request, and send them through the contact page. Do not send the PDF itself unless support asks for it.

Should I use the SDK, the command line or MCP?

Use the SDK inside TypeScript code, the command line for scripts and batches of local files, and MCP when an AI agent chooses the tool. All three use the same catalog and the same server, so you can combine them.