Documentação API

Autenticação

Todos os pedidos API requerem um token Bearer no Authorization cabeçalho. Gere chaves API a partir de Definições.

curl -H "Authorization: Bearer sg_live_your_key_here" \
     https://siteguardian.io/api/v1/monitors

Limite de pedidos: 120 pedidos por minuto por chave API. Exceder este limite retorna 429 Too Many Requests.

Formato de Resposta

Todas as respostas retornam JSON com uma estrutura consistente:

// Success
{
  "data": { ... },
  "meta": { "timestamp": "2026-03-20T14:30:00+00:00" }
}

// Paginated
{
  "data": [ ... ],
  "meta": { "total": 42, "limit": 50, "offset": 0 }
}

// Error
{
  "detail": "Monitor not found."
}

Endpoints

M Monitores

Método	Endpoint	Descrição
GET	/api/v1/monitors	Listar todos os monitores
POST	/api/v1/monitors	Criar um monitor
GET	/api/v1/monitors/:id	Obter detalhes do monitor
PATCH	/api/v1/monitors/:id	Atualizar definições do monitor
DELETE	/api/v1/monitors/:id	Eliminar monitor
POST	/api/v1/monitors/:id/pause	Pausar monitorização
POST	/api/v1/monitors/:id/resume	Retomar monitorização

Exemplo: Criar um monitor

curl -X POST https://siteguardian.io/api/v1/monitors \
  -H "Authorization: Bearer sg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "name": "My Website",
    "check_type": "all"
  }'

Exemplo: Atualizar definições do monitor

curl -X PATCH https://siteguardian.io/api/v1/monitors/:id \
  -H "Authorization: Bearer sg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "ssl_warn_days": 14,
    "rt_alert_enabled": true,
    "rt_sensitivity": 2.5
  }'

C Resultados das Verificações

Método	Endpoint	Descrição
GET	/api/v1/monitors/:id/checks	Listar resultados de verificações (paginado)
GET	/api/v1/monitors/:id/uptime	Obter percentagem de disponibilidade

Parâmetros de consulta

limit – Resultados por página (1-500, predefinido 50)

offset – Saltar N resultados (predefinido 0)

check_type – Filtro: http, ssl, domain, email, pagespeed

days – Período de cálculo de disponibilidade (1-365, predefinido 30)

A Alertas

Método	Endpoint	Descrição
GET	/api/v1/alerts	Listar alertas recentes (paginado)
GET	/api/v1/alerts/:id	Obter alerta individual

I Incidentes

Método	Endpoint	Descrição
GET	/api/v1/incidents	Listar incidentes (filtro: `?status=open`)
PATCH	/api/v1/incidents/:id/acknowledge	Confirmar receção do incidente
PATCH	/api/v1/incidents/:id/resolve	Resolver incidente

Exemplo: Resolver um incidente

curl -X PATCH https://siteguardian.io/api/v1/incidents/:id/resolve \
  -H "Authorization: Bearer sg_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "note": "Fixed the DNS configuration" }'

K Chaves API

Método	Endpoint	Descrição
POST	/api/v1/api-keys	Gerar nova chave API (retorna a chave uma vez)
GET	/api/v1/api-keys	Listar chaves API (apenas prefixo)
DELETE	/api/v1/api-keys/:id	Revogar chave API

Importante: A chave API completa só é retornada uma vez quando criada. Guarde-a de forma segura – apenas mantemos um hash.

Tipos de Alerta

Tipo	Descrição
down	O monitor está inativo (erro HTTP ou timeout)
recovered	O monitor recuperou da inatividade
ssl_expiring	O certificado SSL expira dentro do limiar
domain_expiring	O domínio expira dentro do limiar
response_time	Anomalia no tempo de resposta detetada
email_blacklisted	IP listado em lista negra DNS
email_issues	Problema crítico de saúde de email (SPF/DKIM/DMARC)

Códigos de Estado HTTP

Código	Significado
200	Sucesso
201	Recurso criado
400	Pedido inválido (entrada inválida)
401	Não autorizado (chave API em falta ou inválida)
403	Proibido (limite do plano atingido)
404	Recurso não encontrado
429	Limite de pedidos excedido