Feito para agentes de IA, não só para navegadores: como a API funciona

Uma aba do navegador continua funcionando: escolha uma ferramenta, envie um arquivo, baixe o resultado. Agentes e scripts chamam as mesmas operações sem abrir interface nenhuma. Os dois caminhos chegam ao mesmo catálogo.

Toda página de ferramenta também é um endpoint

Mesclar, dividir, comprimir, OCR, converter: cada ferramenta do catálogo corresponde a um caminho em /api/v1/…. Abra a página de uma ferramenta e desça até Call this from code para ver um exemplo de curl montado com os parâmetros reais daquela ferramenta, não um modelo genérico. Chamadas anônimas não exigem conta nem chave de API no site público; os prefixos anônimos são /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ e /api/v1/filter/.

O exemplo de merge é concreto:

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

A especificação OpenAPI fica em /v1/openapi.json. Trabalho em várias etapas usa POST /api/v1/pipeline com uma lista ordenada em steps. Envie Idempotency-Key quando uma nova tentativa não puder executar duas vezes um job que altera estado. Respostas no servidor hospedado trazem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; em HTTP 429, leia Retry-After (limite de requisições anônimas).

O OCR pelo mesmo catálogo devolve Markdown (text/markdown) em /api/v1/misc/ocr-pdf, e não um PDF com camada de texto escondida. Um agente que espere um PDF pesquisável desse endpoint vai lidar mal com o download; o contrato é extração de texto para pipelines, não uma reescrita no estilo OCRmyPDF.

MCP para clientes que falam o protocolo

O MCP (Model Context Protocol) permite que clientes de agente descubram e invoquem ferramentas como funções, em vez de raspar documentação. Este site expõe um servidor MCP em /mcp, ao lado da API REST, então um cliente compatível se conecta uma vez e recebe o catálogo inteiro.

MCP e REST compartilham as mesmas expectativas de autenticação: anônimo onde os prefixos de ferramenta permitem; chaves de API para automação estável e para servidores self-hosted com controle de acesso. Apontar um agente para /mcp não é um produto diferente de apontar o curl para /api/v1/…. Documentação: MCP para desenvolvedores.

Os erros são estruturados, não texto solto

Uma falha devolve application/problem+json (no estilo RFC 7807), não um 500 cru nem "algo deu errado". Cada payload traz um código estável (rate_limited, bad_request, invalid_document, missing_dependency e outros), uma dica legível e, muitas vezes, um próximo passo. Uma pessoa consegue bater o olho; um agente consegue decidir entre tentar de novo, trocar o arquivo ou parar, sem ninguém interpretar um stack trace.

Quando quem chama é um script, essa estrutura vale mais do que uma página de erro em HTML amigável. Referência: Erros para desenvolvedores.

O llms.txt é para ferramentas, não para ranking

O /llms.txt é um índice em texto puro de cada ferramenta (nome, descrição curta, URL), gerado a partir do mesmo catálogo que alimenta o site. Agentes de código e ferramentas de documentação conseguem lê-lo como um README. Ele não é alavanca de ranking no Google: a Busca ignora o /llms.txt (fontes: guia do Google para otimização com IA). Como é gerado, ele não fica desatualizado em silêncio como um arquivo editado à mão.

CLI e skill compartilham os mesmos formatos

O pdfx roda o pdf-core local ou o modo --cloud contra uma URL base. A skill para agentes de código em dist/skills/pdf-toolbox/SKILL.md documenta os formatos de curl de merge e pipeline, para que os agentes não inventem um segundo contrato. Quatro clientes, um catálogo: A mesma operação em quatro clientes.

O caminho pelo navegador segue igual

Arrastar um arquivo para a aba continua funcionando do mesmo jeito. A superfície extra são os mesmos endpoints para um agente, um script ou o CI: o mesmo processamento, sem ninguém no meio. O self-host mantém essa superfície na sua rede (Self-host); o serviço hospedado segue como caminho de teste anônimo.

Referência da API: Swagger. Para começar em qualquer um dos caminhos: Ajuda e Desenvolvedores.