API Reference

Integre o SAFETAGGY ao seu pipeline de CI/CD, dashboards ou ferramentas internas.

Autenticação

A API usa chaves de API (API keys) para autenticação. Gere uma chave em Configurações → API Keys.

Envie a chave no header Authorization:

curl -H "Authorization: Bearer stk_sua_chave_aqui" \
  https://www.safetaggy.com.br/api/v1/scans

Chaves começam com o prefixo stk_. A chave completa é exibida apenas uma vez, no momento da criação.

URL base

https://www.safetaggy.com.br/api/v1

Endpoints

POST/v1/scans— Iniciar uma varredura

Cria uma nova varredura de segurança. A varredura é executada em background.

Request body

{
  "url": "https://exemplo.com.br",
  "appType": "saas",       // saas | ecommerce | api | landing | other
  "consent": true           // obrigatório — confirma autorização
}

Response (201)

{
  "id": "cm3abc123...",
  "status": "queued"
}

GET/v1/scans— Listar varreduras

Retorna as últimas 10 varreduras concluídas da sua conta.

Response (200)

{
  "scans": [
    {
      "id": "cm3abc123...",
      "targetUrl": "https://exemplo.com.br",
      "status": "completed",
      "overallScore": 72,
      "completedAt": "2026-03-16T14:30:00Z",
      "findings": {
        "critical": 1,
        "high": 3,
        "medium": 5,
        "low": 2,
        "info": 4
      }
    }
  ]
}

GET/v1/scans/:id— Detalhes da varredura

Retorna todos os detalhes de uma varredura, incluindo achados individuais, tech stack, cobertura e resumo por categoria.

Response (200)

{
  "id": "cm3abc123...",
  "targetUrl": "https://exemplo.com.br",
  "status": "completed",
  "overallScore": 72,
  "techStack": ["Next.js", "React", "Vercel"],
  "findings": [
    {
      "id": "find_xyz...",
      "categoryName": "Security Headers",
      "checkName": "csp-header",
      "severity": "high",
      "title": "Content-Security-Policy ausente",
      "description": "O header CSP não foi encontrado...",
      "recommendation": "Adicione o header Content-Security-Policy..."
    }
  ],
  "categorySummary": {
    "security-headers": { "score": 40, "total": 8, "passed": 3 }
  }
}

Rate limits

Limite	Valor
Varreduras por dia	Conforme seu plano (5 / 30 / ilimitado)
Mesmo domínio	Max 10 por hora
Cooldown entre scans	30–60 segundos por domínio

Quando o limite é atingido, a API retorna 429 Too Many Requests.

Códigos de erro

Status	Code	Descrição
401	`unauthorized`	API key ausente ou inválida
400	`invalid_url`	URL inválida ou não acessível
429	`plan_limit`	Limite diário do plano atingido
429	`domain_rate_limit`	Muitas varreduras no mesmo domínio

Limites de API keys por plano

Plano	API Keys
Essencial	Não disponível
Profissional	Até 3 chaves
Business	Até 10 chaves