Built for AI Agents, Not Just Browsers: How the API Works
Every catalog tool is a REST endpoint under /api/v1/, plus MCP at /mcp. Anonymous calls need no account or API key. Failures return RFC 7807 problem+json.
A browser tab still works: pick a tool, upload a file, download the result. Agents and scripts call the same operations without opening a UI. Both paths hit the same catalog.
Every tool page is also an endpoint
Merge, split, compress, OCR, convert: every catalog tool maps to /api/v1/…. Open a tool page and scroll to Call this from code for a curl example built from that tool’s real parameters, not a generic template. Anonymous calls need no account and no API key on the public site; the anonymous prefixes are /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/, and /api/v1/filter/.
The merge example is concrete:
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
OpenAPI lives at /v1/openapi.json. Multi-step work uses POST /api/v1/pipeline with an ordered steps list. Send Idempotency-Key when a retry must not double-run a mutating job. Hosted responses advertise X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; on HTTP 429, read Retry-After (anonymous rate limiting).
OCR through the same catalog returns Markdown (text/markdown) from /api/v1/misc/ocr-pdf, not a PDF with a hidden text layer. Agents that expect a searchable PDF from that endpoint will mis-handle the download; the contract is text extraction for pipelines, not OCRmyPDF-style rewrite.
MCP for clients that speak it
MCP (Model Context Protocol) lets agent clients discover and invoke tools as functions instead of scraping docs. This site exposes an MCP server at /mcp beside the REST API, so a compatible client connects once and gets the full catalog.
MCP and REST share auth expectations: anonymous where the tool prefixes allow it; API keys for stable automation and for gated self-hosted servers. Pointing an agent at /mcp is not a different product from pointing curl at /api/v1/…. Docs: Developers MCP.
Errors are structured, not prose
Failures return application/problem+json (RFC 7807 style), not a bare 500 or “something went wrong.” Each payload has a stable code (rate_limited, bad_request, invalid_document, missing_dependency, and peers), a readable hint, and often a next step. Humans can skim it; agents can decide retry, swap the file, or stop without a person parsing a stack trace.
That structure matters more than a friendly HTML error page when the caller is a script. Reference: Developers errors.
llms.txt is for tooling, not rankings
/llms.txt is a plain-text index of every tool (name, blurb, URL), generated from the same catalog that drives the site. Coding agents and docs tools can read it like a README. It is not a Google ranking lever: Search ignores /llms.txt (sources: Google’s guide to AI optimization). Because it is generated, it cannot silently go stale the way a hand-edited file can.
CLI and skill share the same shapes
pdfx can run local pdf-core or --cloud against a base URL. The coding-agent skill under dist/skills/pdf-toolbox/SKILL.md documents merge and pipeline curl shapes so agents do not invent a second contract. Four clients, one catalog: Same operation, four clients.
Browser path unchanged
Dropping a file in a tab still works the same. The extra surface is the same endpoints for an agent, a script, or CI: same processing, no human in the middle. Self-host keeps that surface on your network (Self-host); hosted stays the anonymous trial path.
API reference: Swagger. Basics for either path: Help and Developers.