브라우저만이 아니라 AI 에이전트를 위해 만들어진 API
카탈로그의 모든 도구는 /api/v1/ 아래 REST 엔드포인트이고 /mcp에 MCP 서버도 있습니다. 익명 호출에는 계정도 API 키도 필요 없습니다. 실패 응답은 RFC 7807 problem+json입니다.
브라우저 탭은 여전히 쓸 수 있습니다. 도구를 고르고 파일을 올리고 결과를 내려받으면 됩니다. 에이전트와 스크립트는 UI를 열지 않고 같은 연산을 호출합니다. 두 경로 모두 같은 카탈로그에 닿습니다.
모든 도구 페이지가 엔드포인트이기도 합니다
PDF 병합, 분할, 압축, OCR, 변환: 카탈로그의 모든 도구가 /api/v1/…에 대응합니다. 도구 페이지를 열고 Call this from code까지 스크롤하면, 일반 템플릿이 아니라 그 도구의 실제 매개변수로 만든 curl 예제가 나옵니다. 공개 사이트에서 익명 호출에는 계정도 API 키도 필요 없습니다. 익명 접두사는 /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/, /api/v1/filter/입니다.
merge 예제는 구체적입니다.
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
OpenAPI는 /v1/openapi.json에 있습니다. 여러 단계를 잇는 작업은 순서가 있는 steps 목록과 함께 POST /api/v1/pipeline을 씁니다. 재시도가 변경 작업을 두 번 실행하면 안 될 때는 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가 아닙니다. 이 엔드포인트에서 검색 가능한 PDF가 나온다고 기대하는 에이전트는 내려받은 파일을 잘못 다룹니다. 계약은 파이프라인을 위한 텍스트 추출이지 OCRmyPDF식 재작성이 아닙니다.
MCP를 말하는 클라이언트를 위해
MCP(Model Context Protocol)를 쓰면 에이전트 클라이언트가 문서를 긁는 대신 도구를 함수로 발견해 호출합니다. 이 사이트는 REST API 옆 /mcp에 MCP 서버를 노출하므로, 호환 클라이언트는 한 번 연결해 전체 카탈로그를 얻습니다.
MCP와 REST는 인증 기대치를 공유합니다. 도구 접두사가 허용하는 범위에서는 익명이고, 안정적인 자동화와 접근이 제한된 자체 호스팅 서버에는 API 키를 씁니다. 에이전트를 /mcp로 향하게 하는 것은 curl을 /api/v1/…로 향하게 하는 것과 다른 제품이 아닙니다. 문서: 개발자 MCP.
오류는 산문이 아니라 구조입니다
실패는 그냥 500이나 "something went wrong"이 아니라 application/problem+json(RFC 7807 방식)을 반환합니다. 각 본문에는 안정적인 코드(rate_limited, bad_request, invalid_document, missing_dependency 등)와 읽을 수 있는 힌트, 그리고 대개 다음 단계가 들어 있습니다. 사람은 훑어보면 되고, 에이전트는 스택 트레이스를 사람이 해석하지 않고도 재시도할지, 파일을 바꿀지, 멈출지 정할 수 있습니다.
호출자가 스크립트일 때는 친절한 HTML 오류 페이지보다 이 구조가 더 중요합니다. 참고: 개발자 오류.
llms.txt는 도구를 위한 것이지 순위를 위한 것이 아닙니다
/llms.txt는 사이트를 구동하는 같은 카탈로그에서 생성된 모든 도구의 평문 색인(이름, 한 줄 설명, URL)입니다. 코딩 에이전트와 문서 도구가 README처럼 읽을 수 있습니다. Google 순위를 올리는 수단은 아닙니다. 검색엔진은 /llms.txt를 무시합니다(출처: Google의 AI 최적화 가이드). 생성물이므로 손으로 고친 파일처럼 조용히 낡아 버릴 수 없습니다.
CLI와 skill은 같은 형태를 공유합니다
pdfx는 로컬 pdf-core를 돌리거나 --cloud로 base URL을 지정할 수 있습니다. dist/skills/pdf-toolbox/SKILL.md 아래의 coding-agent skill은 merge와 pipeline의 curl 형태를 문서화해, 에이전트가 두 번째 계약을 만들어 내지 않게 합니다. 네 개의 클라이언트, 하나의 카탈로그: 같은 연산, 네 개의 클라이언트.
브라우저 경로는 그대로입니다
탭에 파일을 떨어뜨리는 방식은 예전과 같습니다. 추가된 표면은 에이전트와 스크립트, CI를 위한 같은 엔드포인트입니다. 같은 처리에 중간에 사람이 없습니다. 자체 호스팅은 그 표면을 자체 네트워크에 둡니다(자체 호스팅). 호스팅은 익명 체험 경로로 남습니다.