Costruito per gli agenti AI, non solo per il browser: come funziona l'API
Ogni strumento del catalogo è un endpoint REST sotto /api/v1/, più MCP su /mcp. Le chiamate anonime non richiedono account né API key; gli errori sono RFC 7807.
Una scheda del browser funziona ancora: scegli uno strumento, carichi un file, scarichi il risultato. Agenti e script chiamano le stesse operazioni senza aprire un'interfaccia. Entrambi i percorsi arrivano allo stesso catalogo.
Ogni pagina di strumento è anche un endpoint
Unire, dividere, comprimere, OCR, convertire: ogni strumento del catalogo corrisponde a /api/v1/…. Apri la pagina di uno strumento e scorri fino a Call this from code per un esempio curl costruito con i parametri reali di quello strumento, non con un modello generico. Sul sito pubblico le chiamate anonime non richiedono account né API key; i prefissi anonimi sono /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ e /api/v1/filter/.
L'esempio di merge è concreto:
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
OpenAPI è pubblicato su /v1/openapi.json. Il lavoro in più passaggi usa POST /api/v1/pipeline con una lista ordinata steps. Invia Idempotency-Key quando un nuovo tentativo non deve rieseguire due volte un'operazione che modifica lo stato. Le risposte ospitate espongono X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; su HTTP 429 leggi Retry-After (limite di frequenza anonimo).
L'OCR passa dallo stesso catalogo e restituisce Markdown (text/markdown) da /api/v1/misc/ocr-pdf, non un PDF con uno strato di testo nascosto. Un agente che si aspetta un PDF ricercabile da quell'endpoint gestirà male il download; il contratto è l'estrazione di testo per le pipeline, non una riscrittura in stile OCRmyPDF.
MCP per i client che lo parlano
MCP (Model Context Protocol) permette ai client degli agenti di scoprire e invocare gli strumenti come funzioni, invece di estrarre informazioni dalla documentazione. Questo sito espone un server MCP su /mcp accanto all'API REST, così un client compatibile si collega una volta sola e ottiene l'intero catalogo.
MCP e REST condividono le stesse regole di autenticazione: anonimo dove i prefissi degli strumenti lo consentono, API key per l'automazione stabile e per i server self-hosted protetti. Collegare un agente a /mcp non è un prodotto diverso dal collegare curl a /api/v1/…. Documentazione: Developers MCP.
Gli errori sono strutturati, non prose
Un fallimento restituisce application/problem+json (stile RFC 7807), non un 500 nudo o un «qualcosa è andato storto». Ogni payload ha un codice stabile (rate_limited, bad_request, invalid_document, missing_dependency e simili), un suggerimento leggibile e spesso un passo successivo. Una persona può scorrerlo; un agente può decidere se ritentare, cambiare file o fermarsi, senza che nessuno debba interpretare uno stack trace.
Quando il chiamante è uno script, quella struttura conta più di una pagina HTML di errore amichevole. Riferimento: Developers errors.
llms.txt serve agli strumenti, non al posizionamento
/llms.txt è un indice in testo semplice di ogni strumento (nome, descrizione breve, URL), generato dallo stesso catalogo che alimenta il sito. Gli agenti di programmazione e gli strumenti di documentazione possono leggerlo come un README. Non è una leva per il posizionamento su Google: Search ignora /llms.txt (fonti: guida di Google all'ottimizzazione per l'IA). Poiché è generato, non può diventare obsoleto in silenzio come un file modificato a mano.
CLI e skill condividono le stesse forme
pdfx può eseguire pdf-core in locale oppure --cloud verso un URL di base. La skill per gli agenti di programmazione in dist/skills/pdf-toolbox/SKILL.md documenta le forme curl di merge e pipeline, così gli agenti non inventano un secondo contratto. Quattro client, un catalogo: La stessa operazione, quattro client.
Il percorso nel browser resta invariato
Trascinare un file in una scheda funziona come prima. Ciò che si aggiunge sono gli stessi endpoint per un agente, uno script o la CI: stessa elaborazione, nessun intervento umano. Il self-host tiene quegli endpoint sulla tua rete (Self-host); l'hosting gestito resta il percorso di prova anonimo.
Riferimento API: Swagger. Le basi per entrambi i percorsi: Help e Developers.