{"openapi":"3.1.0","info":{"title":"ABS Core Super Scan API","version":"2026-08-03","description":"Assessment público, read-only e baseado em evidências da superfície digital de uma URL."},"paths":{"/healthz":{"get":{"summary":"Health check público do Worker","responses":{"200":{"description":"Worker disponível"}}}},"/api/super-scan":{"post":{"summary":"Executa um assessment read-only","description":"Coleta a resposta inicial e recursos públicos associados. Não envia formulários, não autentica e não executa JavaScript remoto.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"},"examples":{"commerce":{"value":{"url":"https://exemplo.com","profile":"commerce"}}}}}},"responses":{"200":{"description":"Assessment concluído","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assessment"}}}},"400":{"description":"URL inválida ou auto-auditoria recusada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite por IP, alvo ou plataforma excedido","headers":{"Retry-After":{"schema":{"type":"integer","example":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Alvo inacessível ou timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/seo-scan":{"post":{"summary":"Executa auditoria pública de SEO técnico","description":"Analisa sinais observáveis; não mede ranking, backlinks ou volume.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"keyword":{"type":"string"}}}}}},"responses":{"200":{"description":"Auditoria SEO concluída"},"400":{"description":"URL inválida"},"429":{"description":"Limite excedido"},"502":{"description":"Alvo inacessível"}}}},"/api/v1/scans":{"post":{"summary":"Executa um assessment autenticado e registra o histórico","description":"Requer Authorization: Bearer <API_KEY>. A chave é emitida fora da API pública; o endpoint preserva o modo read-only do scanner.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"Assessment concluído","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assessment"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cota da chave excedida","headers":{"Retry-After":{"schema":{"type":"integer","example":86400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Lista o histórico recente da própria organização","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Execuções recentes"},"401":{"description":"Chave inválida"}}}},"/api/v1/paid-media-scans":{"post":{"summary":"Gera PDF white-label de mídia paga","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrowthRequest"}}}},"responses":{"200":{"description":"PDF da auditoria","content":{"application/pdf":{}}},"401":{"description":"Chave inválida"},"429":{"description":"Cota excedida"}}}},"/api/v1/growth-scans":{"post":{"summary":"Gera diagnóstico integrado de mídia, SEO e descoberta por IA","description":"Separa evidência pública de métricas que exigem Ads, Search Console e dados de SERP.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrowthRequest"}}}},"responses":{"200":{"description":"PDF do diagnóstico integrado","content":{"application/pdf":{}}},"401":{"description":"Chave inválida"},"429":{"description":"Cota excedida"}}}},"/api/v1/monitors":{"get":{"summary":"Lista monitores da própria organização","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Monitores ativos e inativos"},"401":{"description":"Chave inválida"}}},"post":{"summary":"Cria monitor read-only agendado","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"},"profile":{"type":"string","enum":["auto","content","api","commerce"]},"cadenceHours":{"type":"integer","minimum":1,"maximum":720,"default":24}}}}}},"responses":{"201":{"description":"Monitor criado"},"400":{"description":"Parâmetros inválidos"},"401":{"description":"Chave inválida"}}}},"/api/v1/monitors/{id}":{"delete":{"summary":"Desativa um monitor","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Monitor desativado"},"404":{"description":"Monitor ausente"}}}},"/api/v1/overview":{"get":{"summary":"Resumo operacional da própria organização","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Contagens de scans, monitores e execuções recentes"},"401":{"description":"Chave inválida"}}}},"/api/v1/webhooks":{"get":{"summary":"Lista webhooks da própria organização","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Webhooks ativos e inativos"},"401":{"description":"Chave inválida"}}},"post":{"summary":"Cria webhook HTTPS assinado para mudanças de monitor","description":"Retorna signingSecret uma única vez. As entregas levam X-ABS-Timestamp e X-ABS-Signature (HMAC-SHA-256 de timestamp.payload); não seguem redirects e tentam até três vezes para erro de rede/5xx.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"URL HTTPS pública"},"minScoreDelta":{"type":"number","minimum":0,"maximum":100,"default":5}}}}}},"responses":{"201":{"description":"Webhook e segredo de assinatura de uso único"},"400":{"description":"URL ou limiar inválido"},"401":{"description":"Chave inválida"},"503":{"description":"Assinatura indisponível"}}}},"/api/v1/webhooks/{id}":{"delete":{"summary":"Desativa um webhook","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Webhook desativado"},"404":{"description":"Webhook ausente"}}}},"/api/v1/webhooks/{id}/deliveries":{"get":{"summary":"Lista tentativas de entrega do webhook","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Entregas recentes, com status HTTP ou erro"},"404":{"description":"Webhook ausente ou de outra organização"}}}},"/api/v1/browser-observations":{"post":{"summary":"Observa uma página renderizada","description":"Sem login, interação ou formulário; não altera o score estático.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"Métricas de renderização, CWV observáveis e ativos"},"429":{"description":"Cota de 10 renderizações por hora"},"502":{"description":"Renderização indisponível ou alvo inacessível"}}}},"/api/v1/seo-crawl":{"post":{"summary":"Faz crawl SEO estático e sequencial","description":"Visita até dez páginas do mesmo domínio; não executa JavaScript nem segue redirects.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri"},"maxPages":{"type":"integer","minimum":1,"maximum":10,"default":5}}}}}},"responses":{"200":{"description":"Páginas, títulos, canonicals e links com erro observados"},"429":{"description":"Cota de 5 crawls por hora"},"502":{"description":"Alvo inacessível"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ABS API key"}},"schemas":{"ScanRequest":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL HTTP(S) pública; destinos privados e loopback são recusados."},"profile":{"type":"string","enum":["auto","content","api","commerce"],"default":"auto"}}},"GrowthRequest":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048},"keyword":{"type":"string","maxLength":200,"description":"Termo alvo de SEO"},"keywords":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":100},"description":"Termos/copy do anúncio"},"agency":{"type":"string","maxLength":120,"description":"Marca white-label"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Dimension":{"type":"object","required":["score","measured"],"properties":{"score":{"type":"number","minimum":0,"maximum":100},"measured":{"type":"boolean"}}},"Finding":{"type":"object","required":["id","pillar","title","evidence","impact","businessImpact","audience","severity","priority","recommendation","effort","references"],"properties":{"id":{"type":"string"},"pillar":{"type":"string","enum":["readiness","aeo","lighthouseAgentic","securityGovernance"]},"title":{"type":"string"},"evidence":{"type":"string"},"impact":{"type":"string"},"businessImpact":{"type":"string"},"audience":{"type":"array","items":{"type":"string","enum":["executive","marketing","development","security"]}},"severity":{"type":"string","enum":["High","Medium","Low","Informational"]},"priority":{"type":"integer","minimum":1},"recommendation":{"type":"string"},"effort":{"type":"string","enum":["Baixo","Médio"]},"references":{"type":"array","items":{"type":"object","required":["label","url"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}},"Assessment":{"type":"object","required":["scanId","requestId","url","timestamp","globalScore","grade","profile","mode","checksSummary","commerceRisk","findings","dimensions","pillars","criticalIssues"],"properties":{"scanId":{"type":"string","format":"uuid","description":"Identificador da execução."},"requestId":{"type":"string","description":"Identificador de correlação da requisição de borda."},"url":{"type":"string","format":"uri"},"timestamp":{"type":"string","format":"date-time"},"globalScore":{"type":"number","minimum":0,"maximum":100},"grade":{"type":"string","enum":["A","B","C","D","F"]},"profile":{"type":"string","enum":["content","api","commerce"]},"mode":{"type":"string","enum":["static"]},"checksSummary":{"type":"object","required":["passed","total"],"properties":{"passed":{"type":"integer"},"total":{"type":"integer"}}},"commerceRisk":{"type":["object","null"],"description":"Detalhe adicional somente quando o perfil resolvido é commerce."},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"dimensions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Dimension"},"description":"Sete dimensões calculadas apenas a partir de checks estáticos medidos."},"pillars":{"type":"object","description":"Agrupamentos legados da matriz global de pontuação."},"criticalIssues":{"type":"array","items":{"type":"object"}}}}}}}