Зроблено для AI-агентів, а не лише для браузерів: як працює API

Вкладка браузера й далі працює: виберіть інструмент, завантажте файл, звантажте результат. Агенти та скрипти викликають ті самі операції, не відкриваючи інтерфейсу. Обидва шляхи ведуть до одного каталогу.

Кожна сторінка інструменту — це також кінцева точка

Об’єднати, розділити, стиснути, розпізнати, конвертувати: кожен інструмент каталогу відповідає шляху /api/v1/…. Відкрийте сторінку інструменту й прокрутіть до розділу з прикладом виклику з коду — там наведено curl, зібраний із реальних параметрів саме цього інструменту, а не загальний шаблон. Анонімні виклики на публічному сайті не потребують ні облікового запису, ні ключа API; анонімні префікси — /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 (анонімне обмеження швидкості).

Розпізнавання через той самий каталог повертає Markdown (text/markdown) з /api/v1/misc/ocr-pdf, а не PDF із прихованим текстовим шаром. Агент, який очікує від цієї кінцевої точки PDF із пошуком по тексту, неправильно обробить звантажений файл; контракт — витягування тексту для конвеєрів, а не перепис у стилі OCRmyPDF.

MCP для клієнтів, які його розуміють

MCP (Model Context Protocol) дає клієнтам-агентам змогу знаходити інструменти й викликати їх як функції, а не збирати документацію зі сторінок. Цей сайт відкриває сервер MCP на /mcp поряд із REST API, тож сумісний клієнт підключається один раз і отримує весь каталог.

MCP і REST мають однакові очікування щодо автентифікації: анонімно там, де це дозволяють префікси інструментів; ключі API — для стабільної автоматизації та для закритих серверів на власному хостингу. Спрямувати агента на /mcp — це не інший продукт, ніж спрямувати curl на /api/v1/…. Документація: MCP для розробників.

Помилки структуровані, а не описані словами

Збої повертають application/problem+json (у стилі RFC 7807), а не голий код 500 чи «щось пішло не так». Кожне тіло відповіді містить стабільний код (rate_limited, bad_request, invalid_document, missing_dependency тощо), зрозумілу підказку й часто наступний крок. Людина може пробігти його очима; агент може вирішити повторити спробу, замінити файл або зупинитися, і нікому не доведеться розбирати стек викликів.

Коли виклик робить скрипт, ця структура важить більше за привітну HTML-сторінку помилки. Довідка: Помилки для розробників.

llms.txt — для інструментів, а не для позицій у пошуку

/llms.txt — це простий текстовий покажчик усіх інструментів (назва, короткий опис, URL), згенерований із того самого каталогу, що керує сайтом. Агенти для програмування й інструменти документації можуть читати його як README. Це не важіль для позицій у Google: пошук ігнорує /llms.txt (джерела: путівник Google з оптимізації для ШІ). Оскільки файл згенерований, він не може тихо застаріти так, як це буває з файлом, відредагованим вручну.

CLI і навичка мають ті самі форми

pdfx уміє запускати локальний pdf-core або працювати з --cloud проти базової адреси. Навичка для агентів-програмістів у dist/skills/pdf-toolbox/SKILL.md описує форми curl для об’єднання й конвеєра, щоб агенти не вигадували другого контракту. Чотири клієнти, один каталог: Та сама операція, чотири клієнти.

Шлях через браузер без змін

Перетягнути файл у вкладку працює так само. Додаткова поверхня — ті самі кінцеві точки для агента, скрипта чи CI: та сама обробка, без людини посередині. Власний хостинг тримає цю поверхню у вашій мережі (Власний хостинг); хмарний сервіс лишається анонімним пробним шляхом.

Довідник API: Swagger. Основи для будь-якого шляху: Довідка і Розробникам.