為 AI Agent 而建，不只為瀏覽器：API 怎麼用
每個工具頁都是 /api/v1/ 下的 REST 端點，另有 /mcp 上的 MCP。匿名呼叫免帳號、免 API Key，失敗回傳 RFC 7807 problem+json。
瀏覽器分頁照樣可用：挑一個工具、上傳檔案、下載結果。Agent 和腳本則不開 UI，直接呼叫同一批操作。兩條路徑打到的都是同一份目錄。
每個工具頁同時也是一個端點
合併、拆分、壓縮、OCR、轉換：目錄裡的每個工具都對應到 /api/v1/… 上的一個端點。打開工具頁、往下捲到 Call this from code，裡面會是一段 curl，參數取自該工具的真實表單，而不是通用範本。在公開網站上匿名呼叫既不需要帳號也不需要 API Key，匿名前綴包括 /api/v1/general/、/api/v1/misc/、/api/v1/security/、/api/v1/convert/ 和 /api/v1/filter/。
合併的範例很具體：
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
OpenAPI 放在 /v1/openapi.json。多步驟工作用 POST /api/v1/pipeline，傳入一份有序的 steps 清單。若重試不能讓變更型工作重複執行，請帶上 Idempotency-Key。代管回應會附上 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset；遇到 HTTP 429 時讀 Retry-After（匿名限流）。
同一份目錄裡的 OCR 由 /api/v1/misc/ocr-pdf 回傳 Markdown（text/markdown），不是帶隱藏文字層的 PDF。如果 Agent 以為這個端點會給出可搜尋的 PDF，就會錯誤處理下載結果；這裡的契約是給管線用的文字抽取，不是 OCRmyPDF 那樣重寫 PDF。
給會說 MCP 的用戶端
MCP（Model Context Protocol）讓 Agent 用戶端把工具當成函式來探索與呼叫，不必去爬文件。本站在 REST API 旁邊、/mcp 上提供一個 MCP 伺服器，相容的用戶端連線一次就能拿到完整目錄。
MCP 與 REST 的認證預期一致：工具前綴允許的地方可以匿名；穩定自動化與受控管的自架伺服器則用 API Key。把 Agent 指向 /mcp，和把 curl 指向 /api/v1/…，並不是兩套不同產品。文件見開發者 MCP。
錯誤是結構化的，不是散文
失敗時回傳 application/problem+json（RFC 7807 風格），不是單純的 500，也不是一句「出了點問題」。每份內容都帶有穩定的錯誤碼（rate_limited、bad_request、invalid_document、missing_dependency 等同類項目）、可讀的提示，通常還有下一步建議。人掃一眼就懂，Agent 也能據此決定要重試、換檔案還是停下來，不需要有人去讀堆疊。
當呼叫方是腳本時，這種結構比一個友善的 HTML 錯誤頁重要得多。參考開發者錯誤。
llms.txt 是給工具讀的，不是給排名用的
/llms.txt 是全部工具的純文字索引（名稱、一句簡介、URL），由驅動整個網站的同一份目錄產生。編碼 Agent 和文件工具可以把它當成 README 來讀。它不是 Google 的排名槓桿：Search 會忽略 /llms.txt（出處：Google 的 AI 最佳化指南）。因為它是由目錄產生，不會像手寫檔案那樣悄悄過期。
CLI 與 skill 共用同一套形狀
pdfx 可以跑本機 pdf-core，也可以用 --cloud 指向某個 base URL。dist/skills/pdf-toolbox/SKILL.md 底下的編碼 Agent skill 記錄了 merge 與 pipeline 的 curl 形狀，免得 Agent 自己發明第二套契約。四個用戶端，一份目錄：同一操作，四種用戶端。
瀏覽器路徑沒有改變
在分頁裡丟檔案，用法照舊。多出來的是同一批端點，供 Agent、腳本或 CI 使用：同樣的處理，中間不需要人。自架會把這套介面留在你自己的網路裡（自架）；代管則仍是匿名試用路徑。