Zelfde operatie, vier clients: browser, curl, MCP, pdfx
Dezelfde PDF123-merge via vier clients: het browserformulier, curl naar /api/v1/general/merge-pdfs, MCP op /mcp, en de pdfx CLI tegen uw API-basis.

Vier clients zien eruit als vier producten. Ze delen één catalogus. Neem Merge als concrete taak: PDF's samenvoegen in uploadvolgorde zonder pagina's tot afbeeldingen te rasteren. Hetzelfde patroon geldt voor elke andere catalogustool (compress, OCR, conversie en de rest): één bewerkings-id, vier manieren om die aan te roepen.
Browser
Open /merge, voeg bestanden toe in de volgorde die u wilt, klik op Process en download. Voor catalogustools is geen account nodig. Het blok “Call this from code” op de pagina bouwt curl uit dezelfde velden die het formulier verstuurt, zodat de UI en het HTTP-contract op elkaar afgestemd blijven.
Dat blok is geen marketingtekst. Het wordt gegenereerd uit de tooldefinitie die de portal al voor het formulier gebruikt, en daarom verschijnt een naamswijziging van een parameter op beide plekken tegelijk. Accepteert het formulier de optionele parameter sortType=byFileName, dan kan het curl-voorbeeld hetzelfde veld meenemen.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Anonieme catalogusaanroepen hebben geen sleutel nodig. Sleutels van Developers geven automatisering een stabiele identiteit (en self-hosted servers een drempel). OpenAPI staat op /v1/openapi.json.
Voor taken in meerdere stappen accepteert POST /api/v1/pipeline een geordende reeks bewerkingen in een veld steps (bijvoorbeeld eerst samenvoegen, dan watermerken, dan comprimeren). Stuur Idempotency-Key mee wanneer nieuwe pogingen het werk niet dubbel mogen uitvoeren; een geslaagde herhaling kan terugkomen met Idempotency-Replayed. Mislukkingen gebruiken application/problem+json met stabiele codes zoals rate_limited en bad_request (Developers errors).
Gehoste antwoorden vermelden ook X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset; HTTP 429 bevat Retry-After. Behandel die headers als het actuele budget, niet als een getal dat u uit een blogartikel hebt onthouden (anonieme rate limiting).
MCP
Agents die Model Context Protocol spreken, verbinden met /mcp, ontdekken merge als tool en roepen die aan met hetzelfde verhaal over API-sleutels als REST. Documentatie: Developers MCP.
MCP is geen tweede catalogus. Het is een protocol voor ontdekken en aanroepen bovenop dezelfde bewerkingen die OpenAPI vermeldt. Ontbreekt een bewerking in MCP, dan is dat een serverfout en geen aparte productroute. Combineer MCP met /llms.txt wanneer u een index in proza van de tools wilt voordat de client verbinding maakt.
pdfx CLI
pdfx --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
Dezelfde multipart-vorm als de curl hierboven, waarbij de API-basis standaard de gehoste is. Wat de CLI toevoegt is shell-ergonomie: -o accepteert een map en overschrijft nooit een bestaand bestand, meerdere invoer lopen als een batch met --concurrency, en een batch meldt één regel input -> saved per bestand, met fouten op stderr terwijl de rest blijft doorlopen. pdfx list en pdfx describe <tool> lezen de catalogus die de portal toont, en de gepubliceerde skill op /skills/pdf123.md documenteert dezelfde merge- en pipeline-vormen, zodat agents geen tweede OpenAPI verzinnen.
OCR levert via elk van deze clients nog steeds Markdown uit /api/v1/misc/ocr-pdf, geen verborgen tekstlaag. Dat feit hoort bij het gedeelde contract: het retourtype in één client wijzigen zonder de andere aan te passen, zou de belofte van “dezelfde bewerking” breken. Compress blijft op /api/v1/misc/compress-pdf voor streamrecompressie; het is een andere bewerking dan merge, bereikbaar op dezelfde vier manieren.
Waarom gelijkheid belangrijk is
Zouden browser-merge en API-merge ooit uiteenlopen, dan zouden automatiseringen stil achteruitgaan terwijl de demopagina er nog goed uitzag. Eén bewerking, vier manieren: dat is het punt. De portal is een gemaksclient, geen tweede implementatie van merge, compress of OCR.
Daarom is er ook geen desktopvariant: een vijfde UI-boom zou hetzelfde probleem van uiteenlopende versies opnieuw creëren onder een andere programmanaam. Breder kader: Built for AI agents, not just browsers. Voor de beslissing over desktop, zie Why we skipped the desktop app. Voor het opzetten van de API op uw netwerk, zie Self-host.