Conçu pour les agents IA, pas seulement pour les navigateurs : comment fonctionne l’API
Chaque outil est exposé en REST sous /api/v1/, plus MCP à /mcp. Les appels anonymes n’exigent ni compte ni clé ; les erreurs renvoient problem+json RFC 7807.
Un onglet de navigateur reste utile : on choisit un outil, on téléverse un fichier, on télécharge le résultat. Les agents et les scripts appellent les mêmes opérations sans interface. Les deux chemins aboutissent au même catalogue.
Chaque page d’outil est aussi un point de terminaison
Fusionner, découper, compresser, OCR, convertir : chaque outil du catalogue correspond à un point de terminaison /api/v1/…. Ouvrez une page d’outil : la section Appeler depuis le code donne un exemple curl bâti sur les paramètres réels de l’outil, et non sur un modèle générique. Les appels anonymes n’exigent ni compte ni clé API sur le site public ; les préfixes anonymes sont /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ et /api/v1/filter/.
L’exemple de fusion est concret :
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
OpenAPI est publié à /v1/openapi.json. Un enchaînement multi-étapes passe par POST /api/v1/pipeline avec une liste ordonnée steps. Envoyez Idempotency-Key quand un réessai ne doit pas réexécuter une tâche qui modifie l’état. Les réponses hébergées exposent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; sur un HTTP 429, lisez Retry-After (limitation de débit anonyme).
L’OCR, dans le même catalogue, renvoie du Markdown (text/markdown) depuis /api/v1/misc/ocr-pdf, et non un PDF doté d’une couche de texte cachée. Un agent qui attend de ce point de terminaison un PDF interrogeable traitera mal le fichier téléchargé : la convention est l’extraction de texte pour des pipelines, pas une réécriture à la manière d’OCRmyPDF.
MCP pour les clients qui le parlent
MCP (Model Context Protocol) permet aux clients d’agents de découvrir et d’invoquer les outils comme des fonctions, au lieu d’extraire la documentation à la main. Ce site expose un serveur MCP à /mcp, à côté de l’API REST : un client compatible s’y connecte une fois et obtient tout le catalogue.
MCP et REST partagent les mêmes attentes d’authentification : anonyme là où les préfixes d’outils l’autorisent, clé API pour une automatisation stable et pour les serveurs auto-hébergés protégés. Pointer un agent vers /mcp n’est pas un autre produit que pointer curl vers /api/v1/…. Documentation : MCP pour les développeurs.
Les erreurs sont structurées, pas rédigées
Les échecs renvoient application/problem+json (style RFC 7807), pas un 500 brut ni « une erreur est survenue ». Chaque réponse porte un code stable (rate_limited, bad_request, invalid_document, missing_dependency, etc.), un message lisible et souvent une étape suivante. Un humain peut le parcourir, un agent décider de réessayer, de changer de fichier ou d’arrêter sans qu’une personne déchiffre une trace de pile.
Cette structure compte davantage qu’une page d’erreur HTML conviviale quand l’appelant est un script. Référence : Erreurs pour les développeurs.
llms.txt sert aux outils, pas au classement
/llms.txt est un index en texte brut de tous les outils (nom, description courte, URL), généré à partir du catalogue du site. Les agents de codage et les outils de documentation le lisent comme un README. Ce n’est pas un levier de classement Google : Search ignore /llms.txt (sources : guide de Google pour l’optimisation avec l’IA). Généré, il ne peut pas se périmer en silence comme un fichier modifié à la main.
CLI et compétence d’agent partagent les mêmes formes
pdfx peut exécuter pdf-core en local ou --cloud contre une URL de base. La compétence d’agent de codage fournie dans dist/skills/pdf-toolbox/SKILL.md documente les formes curl pour la fusion et le pipeline, pour que les agents n’inventent pas une seconde convention. Quatre clients, un catalogue : Une même opération, quatre clients.
Le chemin navigateur ne change pas
Déposer un fichier dans un onglet fonctionne toujours pareil. La surface supplémentaire, ce sont les mêmes points de terminaison pour un agent, un script ou la CI : même traitement, sans humain au milieu. L’auto-hébergement garde cette surface sur votre réseau (Auto-hébergement) ; la version hébergée reste le chemin d’essai anonyme.
Référence API : Swagger. Notions de base pour l’un ou l’autre chemin : Aide et Développeurs.