Gebouwd voor AI-agents, niet alleen browsers: hoe de API werkt

Een browsertab werkt nog steeds: kies een tool, upload een bestand, download het resultaat. Agents en scripts roepen dezelfde bewerkingen aan zonder een UI te openen. Beide paden komen uit op dezelfde catalogus.

Elke toolpagina is ook een endpoint

Merge, split, compress, OCR, convert: elke catalogustool verwijst naar /api/v1/…. Open een toolpagina en scrol naar Call this from code voor een curl-voorbeeld dat uit de echte parameters van die tool is opgebouwd, niet uit een generiek sjabloon. Anonieme aanroepen hebben op de openbare site geen account en geen API-sleutel nodig; de anonieme prefixen zijn /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ en /api/v1/filter/.

Het merge-voorbeeld is concreet:

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

OpenAPI staat op /v1/openapi.json. Werk in meerdere stappen gebruikt POST /api/v1/pipeline met een geordende lijst steps. Stuur Idempotency-Key mee wanneer een nieuwe poging een wijzigende taak niet tweemaal mag uitvoeren. Gehoste antwoorden vermelden X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset; lees bij HTTP 429 de waarde van Retry-After (anonieme rate limiting).

OCR via dezelfde catalogus levert Markdown (text/markdown) uit /api/v1/misc/ocr-pdf, geen PDF met een verborgen tekstlaag. Agents die van dat endpoint een doorzoekbare PDF verwachten, gaan met de download de fout in; het contract is tekstextractie voor pipelines, niet een herschrijving in de stijl van OCRmyPDF.

MCP voor clients die het protocol spreken

MCP (Model Context Protocol) laat agentclients tools als functies ontdekken en aanroepen in plaats van documentatie te scrapen. Deze site biedt naast de REST API een MCP-server op /mcp, zodat een compatibele client één keer verbinding maakt en de volledige catalogus krijgt.

MCP en REST delen dezelfde verwachtingen rond authenticatie: anoniem waar de toolprefixen dat toestaan, API-sleutels voor stabiele automatisering en voor afgeschermde self-hosted servers. Een agent op /mcp richten is geen ander product dan curl op /api/v1/… richten. Documentatie: Developers MCP.

Fouten zijn gestructureerd, geen proza

Fouten leveren application/problem+json op (in RFC 7807-stijl), geen kale 500 of “something went wrong”. Elke payload heeft een stabiele code (rate_limited, bad_request, invalid_document, missing_dependency en verwante codes), een leesbare hint en vaak een volgende stap. Mensen kunnen het vluchtig doorlezen; agents kunnen bepalen of ze opnieuw proberen, het bestand verwisselen of stoppen, zonder dat iemand een stacktrace hoeft te ontleden.

Die structuur weegt zwaarder dan een vriendelijke HTML-foutpagina wanneer de aanroeper een script is. Referentie: Developers errors.

llms.txt is voor tooling, niet voor rankings

/llms.txt is een index in platte tekst van elke tool (naam, korte beschrijving, URL), gegenereerd uit dezelfde catalogus die de site aandrijft. Coding agents en documentatietools kunnen het als een README lezen. Het is geen hefboom voor Google-ranking: Search negeert /llms.txt (bronnen: gids van Google voor AI-optimalisatie). Omdat het bestand gegenereerd wordt, kan het niet stil verouderen zoals een met de hand bewerkt bestand.

CLI en skill delen dezelfde vormen

pdfx kan lokale pdf-core draaien of met --cloud tegen een basis-URL. De coding-agent-skill onder dist/skills/pdf-toolbox/SKILL.md documenteert de curl-vormen voor merge en pipeline, zodat agents geen tweede contract verzinnen. Vier clients, één catalogus: Same operation, four clients.

Browserpad ongewijzigd

Een bestand in een tab droppen werkt nog hetzelfde. Het extra oppervlak zijn dezelfde endpoints voor een agent, een script of CI: dezelfde verwerking, geen mens ertussen. Self-host houdt dat oppervlak op uw netwerk (Self-host); gehost blijft het anonieme proefpad.

API-referentie: Swagger. Basis voor beide paden: Help en Developers.