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.
| Interface | Best for | Install or address | Guide |
|---|---|---|---|
| REST API | Any language, servers, shell scripts | https://pdf123.xyz/api/v1 | API reference |
| TypeScript SDK | Node, Bun and browser code that needs types | npm install @pdf123/sdk | SDK guide |
| Command line | Terminals, CI jobs, batches of local files | npm install -g @pdf123/cli | CLI guide |
| MCP | AI agents such as Claude Code, Claude Desktop and Cursor | npx -y @pdf123/mcp or https://pdf123.xyz/mcp | MCP 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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfThe same merge with the TypeScript SDK:
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:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfHow 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...
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.pdfThe 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.
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.pdfHow 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?
| Limit | Value |
|---|---|
| File size on the website | 500 MB per file |
| One direct API request body | 100 MiB, multipart framing included |
| Chunked upload | The 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 reason | HTTP status | Meaning |
|---|---|---|
bad_request | 400 | Invalid parameters or multipart body |
password_required | 400 | The PDF is encrypted and no password was sent |
invalid_pdf | 400 | The file is not a PDF or is damaged; try Repair PDF |
page_out_of_range | 400 | A requested page does not exist |
not_found | 404 | Unknown operation path |
rate_limited | 429 | Quota 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 page | API endpoint | CLI command | What it does |
|---|---|---|---|
| Merge | /general/merge-pdfs | pdfx merge | Combine several PDFs into one |
| Split | /general/split-pages | pdfx split | Divide a PDF into separate files |
| Compress | /misc/compress-pdf | pdfx compress | Recompress PDF streams to reduce size |
| Rotate | /general/rotate-pdf | pdfx rotate | Change page orientation |
| Protect | /security/add-password | pdfx protect | Encrypt a PDF with a password |
| Unlock | /security/remove-password | pdfx unlock | Remove password protection |
| Watermark | /security/add-watermark | pdfx watermark | Add a text or image watermark |
| OCR | /misc/ocr-pdf | pdfx ocr | Read a scanned PDF and return Markdown |
| PDF to Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Convert a PDF into Markdown |
| PDF to Word | /convert/pdf/word | pdfx convert-to-word | Convert a PDF into an editable Word file |
| Document info | /security/get-info-on-pdf | pdfx get-info | Report metadata, permissions, fonts and structure |
| Repair | /misc/repair | pdfx repair | Rebuild 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/mcpserver for files on your machine and the hosted endpoint athttps://pdf123.xyz/mcp. - Load an agent skill. Agent skills are
SKILL.mdfiles 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.jsonlddescribes 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.