Referência da API

Uma API REST pequena e estável para gerenciar monitores e canais e sondar alterações. A mesma área de superfície do dashboard.

URL Base

Produção: https://api.pagedeltas.com. Todos os endpoints têm o prefixo /api. Respostas bem-sucedidas são em JSON.

Autenticação

Crie uma chave em Configurações → Chaves da API (função de editor ou administrador é necessária). A chave é exibida uma vez na criação — copie-a imediatamente. Para revogar uma chave, exclua-a da mesma página.

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

As chaves são limitadas à organização que as criou e atuam com acesso de nível de administrador dentro dessa organização, independentemente de qualquer usuário. Elas não estão vinculadas a um membro, então remover um colega não revoga as chaves da organização — exclua a própria chave para cortar o acesso.

Erros

Os erros retornam um status não-2xx. Erros de autenticação e permissão retornam como uma mensagem curta de texto simples (ex: unauthorized, forbidden); erros de cota e limite de taxa retornam um pequeno corpo JSON com uma mensagem e os números relevantes. Não analise um envelope de erro fixo — faça ramificações no código de status HTTP:

400 — solicitação malformada (JSON inválido, URL inválida, campo faltando).
401 — credenciais ausentes ou inválidas.
403 — autenticado, mas a sua função não tem permissão para essa ação.
404 — recurso faltando ou não está na sua organização.
409 — conflito (ex: o monitor está pausado devido a bloqueios repetidos).
422 — uma cota seria excedida (ex: limite de monitores do seu plano). O corpo JSON inclui current e limit.
429 — limite de taxa excedido (verificações manuais). Aguarde e tente novamente após o atraso em Retry-After.

Exemplo de erro de cota (422):

{
  "error": "plan_url_limit exceeded",
  "current": 100,
  "limit": 100,
  "message": "Creating this monitor would exceed your plan's monitor limit (100)."
}

Referência de endpoints

Método e caminho	Descrição
`GET /api/monitors`	Lista monitores na sua organização.
`POST /api/monitors`	Cria um único monitor.
`GET /api/monitors/{id}`	Obtém um único monitor.
`PATCH /api/monitors/{id}`	Atualiza `url`, `nl_description`, `filter_prompt`, `css_selector`, `xpath_selector`, `status`.
`DELETE /api/monitors/{id}`	Exclui um monitor e o seu histórico.
`POST /api/monitors/{id}/check-now`	Coloca uma verificação imediata na fila, ignorando o agendamento (limite de taxa, veja abaixo).
`GET /api/monitors/{id}/changes`	Lista as alterações detectadas para um monitor (suporta `?limit=`, máx. 100).
`POST /api/monitors/import`	Importação em massa via upload de CSV multipart (campo `file`).
`POST /api/monitors/bulk-pause`, `bulk-resume`, `bulk-delete`	Aplica uma ação a uma lista de IDs de monitores.
`GET\|PUT /api/monitors/{id}/alert-channels`	Lê ou substitui as substituições de canais de um monitor.
`GET /api/alert-channels`	Lista os canais de notificação.
`POST /api/alert-channels`	Cria um canal.
`PATCH\|DELETE /api/alert-channels/{id}`	Atualiza ou exclui um canal.
`POST /api/alert-channels/{id}/test`	Envia um payload de teste para verificar a entrega.
`GET\|POST /api/sitemap-monitors`	Lista ou cria monitores de sitemap.
`POST /api/sitemap-monitors/import`	Cria monitores de sitemap em massa via upload de CSV multipart (campo `file`).
`GET\|POST\|DELETE /api/tokens`	Lista, cria e exclui chaves da API.
`GET /api/billing/plan`	Plano atual e limites da sua organização.
`GET /api/plans`	Público — lista os planos disponíveis (sem necessidade de autenticação).

Exemplo — criar um monitor

curl -X POST https://api.pagedeltas.com/api/monitors \
  -H "Authorization: Bearer $PAGEDELTAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "nl_description": "Competitor pricing; alert on plan or price changes",
    "filter_prompt": "Alert on plan or price changes; ignore copy tweaks",
    "channel_ids": []
  }'

Campos opcionais: filter_prompt, css_selector, xpath_selector, is_pdf e channel_ids (substituições de canais por monitor; omita para usar os padrões da organização). Não há frequency — o agendamento é adaptável.

Exemplo — sondar alterações

GET /api/monitors/01HW2X.../changes?limit=50
Authorization: Bearer $PAGEDELTAS_TOKEN

Retorna as alterações mais recentes primeiro (padrão 50, máx. 100). Não há cursor — faça a paginação ajustando o limit e rastreando o detected_at mais recente que você já viu.

{
  "changes": [
    {
      "id": "01HW3...",
      "detected_at": "2026-06-01T08:42:00Z",
      "summary": "Pro plan increased from $29 to $39/month."
    }
  ]
}

Limites de taxa

Atualmente, não há limites de taxa por chave nos endpoints de leitura e gravação. A única exceção são as verificações manuais:

Check-now: 1 solicitação / minuto / monitor.

Quando você atingir esse limite, a resposta será 429 com um cabeçalho Retry-After em segundos. Por favor, limite sua taxa de forma sensata nos outros endpoints.

Versão

Buscamos manter essa superfície estável. Novos campos e endpoints podem ser adicionados sem aviso prévio, então escreva clientes que ignorem campos JSON desconhecidos.