PDF API overview
Run superPDF tools from your own code over HTTP, on your computer.
superpdf serve runs a small API on your computer that your scripts, apps and automations call to combine, split, convert, protect and inspect PDFs in folders you choose. It offers the same tools, with the same schemas, as the superPDF MCP server for AI agents.
Local only. The API runs on this Mac and listens on 127.0.0.1. Requests carry file paths, not file contents, and documents are never uploaded. The only requests it makes are job notifications to addresses you allow.
How it works
- You start the API in Terminal with the folders it may use, and a token.
- Your code sends JSON to
http://127.0.0.1:7341: a tool name, file paths and options. - The tool runs on this Mac and writes its result as a new file next to your documents. The answer is JSON describing what it did.
- Long work runs as a background job, with a signed event to your own address when it finishes.
Security model
| Protection | What it means |
|---|---|
| This Mac only | The API listens on 127.0.0.1, so other computers on the network can’t reach it. |
| Bearer token | Every /v1 request needs the token the API was started with. See Authentication. |
| Host and Origin checks | Requests must be addressed to 127.0.0.1 or localhost, which stops websites reaching the API through DNS rebinding. Web pages can only call it from origins you allow. |
| Folder scope | Tools read and write only inside the folders passed with --allow-dir. Symbolic links are resolved first, so a link can’t lead outside. |
| New files only | Outputs must not exist yet. Nothing is ever overwritten or deleted. |
| No uploads | Tools never connect to the internet. Job events contain file paths, never document contents. |
Any program on your computer that has the token can use the allowed folders, so keep it private and allow only the folders your code needs.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /v1/tools | List tools |
| POST | /v1/tools/<name> | Run one of 18 tools and return its result. See each tool. |
| POST | /v1/jobs | Run a tool in the background |
| GET | /v1/jobs | List jobs |
| GET | /v1/jobs/{id} | Get a job |
| GET | /openapi.json | This document |
The whole API is described by an OpenAPI 3.1 document: openapi.json. Load it into an API client, or generate a client for your language.
Requirements
macOS, Node.js 22 or later, and the superpdf command (see PDF CLI). pdf_from_office also needs LibreOffice.