PDF API

Call document operations from your app.

Runs superPDF tools from your own scripts and apps through a REST API on your computer: superpdf serve offers the same operations as the MCP server. It accepts only requests from this computer that carry its token, reads and writes only in the folders you allow, and never overwrites files. Requests carry file paths, not file contents, so documents stay where they are.

How to use it

Install the superpdf command (see PDF CLI).
Choose a token and run superpdf serve --allow-dir with the folder the API may use.
Send requests to http://127.0.0.1:7341 with the header Authorization: Bearer <token>, from curl or from TypeScript, Python or Go.

Start the API

In Terminal, set a token, then start the API with the folder it may use:

Terminal

# Choose a token once; your scripts read it from the same variable
export SUPERPDF_API_TOKEN="$(openssl rand -hex 32)"
superpdf serve --allow-dir ~/Documents/superPDF

Output

superPDF API 0.1.0 listening on http://127.0.0.1:7341 (this computer only)
Allowed folders: /Users/<you>/Documents/superPDF
Token: (from SUPERPDF_API_TOKEN)
Webhook secret: whsec_…
OpenAPI: http://127.0.0.1:7341/openapi.json
Send the token as "Authorization: Bearer <token>". Press Ctrl+C to stop.

The API runs until you press Ctrl+C. Scripts read the token from SUPERPDF_API_TOKEN, so export the same value in the Terminal window where you run them.

Call a tool

Each tool is POST /v1/tools/<name> with the tool’s input as JSON. This copies pages 1 to 3 of report.pdf into a new file. The TypeScript, Python and Go examples use a small client file.

curl http://127.0.0.1:7341/v1/tools/pdf_extract_pages \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": "report.pdf", "pages": "1-3", "output": "summary.pdf" }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_extract_pages', {
  input: 'report.pdf',
  pages: '1-3',
  output: 'summary.pdf',
});
console.log(`Wrote ${result.pages} pages to ${result.output}`);

from superpdf import NewFile, call_tool

result: NewFile = call_tool("pdf_extract_pages", {
    "input": "report.pdf",
    "pages": "1-3",
    "output": "summary.pdf",
})
print(f"Wrote {result['pages']} pages to {result['output']}")

package main

import (
	"fmt"
	"log"
)

func main() {
	result, err := CallTool[NewFile]("pdf_extract_pages", map[string]any{
		"input":  "report.pdf",
		"pages":  "1-3",
		"output": "summary.pdf",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Wrote %d pages to %s\n", result.Pages, result.Output)
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/summary.pdf",
  "pages": 3,
  "bytes": 1547
}

API documentation

Quickstart: Start the API and make your first PDF with it in about two minutes.
Authentication: Tokens, the Host and Origin checks, and calling the API from a web page.
Calling tools: A typed client in TypeScript, Python or Go, and the most common tool calls.
Jobs and webhooks: Background jobs, signed completion events, and how to verify them.
Errors: Problem details, every problem code, and how to fix each one.
Endpoint reference: Every endpoint with its fields, limits, responses and a real example.
Limits: File sizes, page counts, request sizes, job queues and webhook timing.
Versioning and changes: How the API is versioned, how it changes, and the changelog.

Privacy

Runs on your computer. The superpdf command-line tool reads and writes files only in the folders you allow, and uploads nothing.