Zelfde operatie, vier clients: browser, curl, MCP, pdfx

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

Lokale pdf-core:

pdfx merge a.pdf b.pdf -o merged.pdf

Of dezelfde server die de portal gebruikt:

pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf

De lokale modus uploadt nooit; de cloudmodus bereikt uw basis-URL met dezelfde multipart-vorm als curl. De coding-agent-skill onder dist/skills/pdf-toolbox/SKILL.md documenteert dezelfde vormen voor merge en pipeline, 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.