Crawlux para desenvolvedores e plataformas.
Documentação de referência para a saída JSON de auditoria do Crawlux (no ar hoje), payloads de webhooks (no ar hoje) e a API REST Crawlux planejada (lançamento em Q4 2026). Além de padrões de integração para agências, plataformas de SEO e sistemas CRM.
Estado atual e roadmap
Três categorias de funcionalidade voltada ao desenvolvedor. Duas estão no ar hoje. Uma será lançada em Q4 2026.
Cada auditoria produz uma saída JSON baixável a partir do dashboard. Os tiers Free, Pro e Team incluem JSON. Estrutura documentada na seção 2.
Configure uma URL de webhook no dashboard. O Crawlux faz POST do JSON completo da auditoria para a URL ao concluir. Apenas tiers Pro e Team. Documentado na seção 3.
Disparo programático de auditorias, polling de status, recuperação de resultados e configuração de webhooks. Referência documentada nas seções 4 a 8 abaixo.
Wrappers de SDK tipados para a API REST. Node.js (npm: crawlux-sdk), Python (pip: crawlux). Documentado na seção 8.
Waitlist de acesso antecipado
A API será lançada no Q4 2026, mas o acesso antecipado abre cerca de 2 semanas antes do lançamento público. Envie um e-mail para [email protected] com o assunto "API Waitlist" para participar. O acesso antecipado é gratuito e inclui revisão da documentação da API.
Estrutura da saída JSON de auditoria
Cada auditoria Crawlux produz um arquivo JSON baixável a partir do dashboard. A estrutura é estável e versionada. Abaixo: a forma top-level e os campos-chave.
"audit_id": "aud_8f3k29vJ7nQ",
"version": "v3",
"domain": "example-protocol.io",
"tier": "team",
"started_at": "2026-04-29T08:14:22Z",
"completed_at": "2026-04-29T08:16:47Z",
"site_category": "defi_protocol",
// Overall score and grade
"score": {
"overall": 67,
"grade": "C+",
"percentile": 58
},
// Per-check-group breakdown
"groups": [
{ "id": "technical", "score": 82, "weight": 0.15 },
{ "id": "schema", "score": 45, "weight": 0.20 },
{ "id": "ymyl", "score": 71, "weight": 0.15 },
{ "id": "ai_visibility", "score": 58, "weight": 0.20 },
{ "id": "authority", "score": 76, "weight": 0.15 },
{ "id": "on_chain", "score": 74, "weight": 0.15 }
],
// Findings array (truncated, full audit returns all 23 analyzers)
"findings": [
{
"analyzer": "B01",
"severity": "high",
"title": "Token page uses generic Product schema",
"recommendation": "Migre para o schema FinancialProduct",
"reference": "crawlux.com/guides/token-schema/"
}
]A saída JSON é a fonte da verdade. Tanto a visualização do dashboard quanto o relatório PDF white-label são gerados a partir desse JSON. Salvar o JSON junto com seu domínio te dá o histórico completo de auditorias.
Campos chave explicados
Identificador único de auditoria. Formato: aud_ seguido por 12 caracteres alfanuméricos. Use-o para recuperar a auditoria depois via dashboard ou (quando a API for lançada) o endpoint GET /audits.
Versão da metodologia usada nessa auditoria. Revisada trimestralmente. O pinning permite auditorias históricas reproduzíveis através de atualizações de versão.
Categoria detectada automaticamente. Valores: defi_protocol, exchange, wallet, nft_platform, infrastructure, identity, generic_crypto. Determina qual conjunto de prompts roda para os testes de AEO.
Código do analisador (A01 a F03, veja a página de metodologia). Mapeia para os 23 analisadores em 6 grupos de verificação. Cada achado cita o analisador específico que foi disparado.
Payloads de webhooks
Configure uma URL de webhook no dashboard. Quando uma auditoria é concluída, o Crawlux faz POST do JSON completo da auditoria para a URL configurada. Útil para disparar automação downstream, popular dados de CRM ou alertar equipes de agência.
// Headers
Content-Type: application/json
X-Crawlux-Event: audit.completed
X-Crawlux-Signature: sha256=a4b8c92e...
X-Crawlux-Audit-Id: aud_8f3k29vJ7nQ
X-Crawlux-Delivery: del_2HxJ4nP3kqM
// Body (full audit JSON, structure as shown in section 2)
{ "audit_id": "aud_8f3k29vJ7nQ", ... }A assinatura do webhook é HMAC-SHA256 computada usando um segredo compartilhado configurado no dashboard. Sempre verifique a assinatura antes de processar o payload.
Disparado quando uma auditoria termina com sucesso. O payload contém o JSON completo da auditoria. O evento mais comum para automação downstream.
Disparado quando uma auditoria não pode ser concluída. O payload contém o audit_id, o código de erro e a mensagem de erro. Causas comuns: domínio inacessível, disallow no robots.txt, rate limit atingido.
Disparado quando uma auditoria com falha é reprocessada automaticamente. Até 3 novas tentativas com backoff exponencial. A falha final produz audit.failed em vez disso.
Garantias de entrega de webhooks
O Crawlux tenta reenviar o webhook até 5 vezes ao longo de 24 horas se o seu endpoint retornar um status diferente de 2xx. Sempre retorne um status 2xx rapidamente (em menos de 5 segundos) e processe o payload de forma assíncrona.
Endpoints API planeados
A API REST do Crawlux será lançada no Q4 2026. Abaixo: a superfície de endpoints planejada. Sujeita a ajustes durante o período de acesso antecipado. URL base: https://api.crawlux.com/v1/.
Dispara uma nova auditoria para um domínio. O body aceita domain (obrigatório), tier (free/pro/team), webhook_url (opcional). Retorna o audit_id e o status da auditoria.
Recupera uma auditoria específica por ID. Retorna o JSON completo da auditoria se estiver concluída ou o objeto de status (queued, running, failed) se ainda não estiver completa.
Lista todas as auditorias no seu workspace. Suporta paginação via parâmetros limit e cursor. Filtra por status, domínio, intervalo de datas. Retorna resumos das auditorias.
Recupera apenas o array de achados de uma auditoria. Resposta mais leve do que o JSON completo da auditoria. Útil para expor achados específicos em dashboards.
Baixa o relatório PDF white-label (apenas tiers Pro e Team). Retorna uma URL assinada válida por 60 minutos. As auditorias de tier gratuito não têm relatórios PDF.
Configura um endpoint de webhook. O body aceita url (obrigatório), events (array de tipos de eventos para assinar), secret (para assinatura HMAC).
Remove uma configuração de webhook. As conclusões de auditoria subsequentes não farão POST para a URL de webhook removida. As auditorias existentes não são afetadas.
Recupera o uso do período atual. Retorna auditorias usadas nesse período, auditorias restantes, data de reset do período e limites do tier. Útil para dashboards de uso.
Autenticação
A API usará autenticação Bearer token. As API keys são geradas por workspace a partir do dashboard do Crawlux. Cada key é escopada a um workspace e a rate limits configuráveis.
Authorization: Bearer crl_live_8f3k29vJ7nQa4b8c92eP3kqM
Content-Type: application/jsonAs API keys vêm em dois ambientes: crl_test_ para testes em sandbox sem consumir cota de auditorias e crl_live_ para auditorias em produção que consomem a cota do plano. As assinaturas de webhooks usam um segredo de assinatura separado, configurado por webhook.
O modo de teste é gratuito
As keys de modo de teste (crl_test_) retornam dados de auditoria realistas, mas sintéticos, sem consumir cota. Útil para criar integrações sem pagar por auditorias reais durante o desenvolvimento.
Limites de uso
Os rate limits escalam com o tier. A cota de auditoria é a restrição vinculante; as chamadas de recuperação de resultados são ilimitadas dentro do razoável.
| Plano | Auditorias / mês | Recuperação de resultados | Use case |
|---|---|---|---|
| Grátis | 5 | Ilimitado | Projetos pessoais, avaliação, equipes de um único domínio |
| Pro | 50 | Ilimitado | Voltado para agências, líderes de SEO internos, consultores multi-projeto |
| Team | 200 | Ilimitado | Agências de marketing, plataformas multi-tenant, equipes de SEO maiores |
| Enterprise | Personalizado | Ilimitado | Infraestrutura dedicada, SLA, suporte de integração personalizado |
Os headers de limite de uso são retornados em toda resposta da API. X-RateLimit-Limit mostra o limite do seu plano. X-RateLimit-Remaining mostra as auditorias restantes. X-RateLimit-Reset é o timestamp Unix em que o limite é reiniciado (início do mês seguinte).
Códigos de error
Os erros retornam JSON com um code, um message e um request_id para solicitações de suporte. Os códigos de status HTTP seguem as convenções REST padrão.
{
"error": {
"code": "audit_quota_exceeded",
"message": "Tier quota exceeded for the current period",
"request_id": "req_2HxJ4nP3kqM8f3k",
"docs_url": "https://www.crawlux.com/docs/#errors"
}
}Formato de domínio inválido ou domínio inacessível. Causas comuns: protocolo ausente, erro de digitação, DNS não propagado, domínio bloqueado pelo registrador.
API key ausente, malformada ou revogada. Verifique o formato do header Authorization. Regenere a key a partir do dashboard se estiver comprometida.
A feature solicitada requer um tier mais alto. Caso comum: configuração de webhook no tier gratuito (Pro ou Team necessário), download de PDF no tier gratuito (Pro ou Team necessário).
Cota mensal de auditoria esgotada para o tier atual. Aguarde até o período ser resetado ou faça upgrade de tier. As chamadas de recuperação de resultados não são afetadas.
Um provedor upstream de dados necessário não está disponível (DataForSEO, CoinGecko, DefiLlama, PageSpeed). A auditoria será reprocessada automaticamente. A página de status cobre as quedas de provedores.
SDKs e bibliotecas cliente
Duas SDKs oficialmente suportadas serão lançadas junto com a API em Q4 2026. SDKs da comunidade em outros idiomas são bem-vindas e serão linkadas a partir dessa página.
import { Crawlux } from 'crawlux-sdk';
const crawlux = new Crawlux({ apiKey: process.env.CRAWLUX_API_KEY });
// Trigger an audit and wait for completion
const audit = await crawlux.audits.run({
domain: 'example-protocol.io',
tier: 'team',
waitForCompletion: true
});
console.log(audit.score.overall); // 67
console.log(audit.findings.length); // 23from crawlux import Crawlux
client = Crawlux(api_key=os.environ["CRAWLUX_API_KEY"])
# Trigger an audit and wait for completion
audit = client.audits.run(
domain="example-protocol.io",
tier="team",
wait_for_completion=True
)
print(audit.score.overall) # 67
print(len(audit.findings)) # 23As duas SDKs fornecem wrappers tipados em torno da API REST, além de helpers para padrões comuns: polling para conclusão de auditoria, verificação de assinatura em webhooks recebidos, disparo de auditorias em lote através de múltiplos domínios.
Padrões comuns de integração
Seis padrões de integração que vemos com mais frequência quando as equipes discutem o acesso antecipado à API. Cada padrão tem uma sequência de endpoints recomendada.
Integração com dashboard de agência
Dispara auditorias por domínio de cliente sob demanda. POST /audits com webhook_url apontando para o seu dashboard. Processa o webhook audit.completed para popular as visualizações de relatórios do cliente.
Automação de cadência trimestral
Um cron job dispara auditorias a cada 90 dias por domínio gerenciado. POST /audits com webhook_url para disparar alertas downstream em caso de regressão de score. Compara o atual com o anterior via o JSON de auditoria salvo.
CRM enrichment
Quando um novo lead entra no CRM, dispara uma auditoria de tier gratuito no domínio dele. Preenche o cadastro do lead com o score e os 3 principais achados. Use como abertura de conversa para ligações de vendas.
Slack alerting
O endpoint de webhook posta no Slack quando a auditoria é concluída. Formata o score e os 3 principais achados em uma mensagem Block Kit. Útil para canais voltados ao cliente e leads de SEO internos.
Embed para plataformas de SEO
Auditorias Crawlux white-label dentro da sua própria UI de plataforma de SEO. Use a API key de teste (crl_test_) durante o build. Mostre os achados na sua própria UI codificados por código de analisador.
Monitoramento massivo de domínios
Dispara auditorias em centenas de domínios gerenciados durante a noite. Faz batch das chamadas POST /audits com sleep entre elas para respeitar os rate limits. Agrega os resultados via sua própria camada de relatórios.
Perguntas comuns de desenvolvedores
Seis perguntas cobrindo o roadmap da API, saída JSON, autenticação, SDKs e rate limits.
Quando a API da Crawlux será lançada?
A API do Crawlux está planejada para Q4 2026. Atualmente as auditorias rodam via o dashboard web do Crawlux com saída JSON baixável por auditoria. A API permitirá disparo programático de auditorias, polling de status, callbacks de webhook e recuperação de resultados. Assine a waitlist de acesso antecipado da documentação para ser notificado quando o acesso à API for aberto.
Posso obter o JSON da auditoria hoje?
Sim. Cada auditoria Crawlux produz uma saída JSON baixável a partir do dashboard de auditoria. A estrutura JSON está documentada nessa página. As auditorias de tier Pro e Team também produzem um relatório PDF white-label. As auditorias de tier gratuito produzem uma saída JSON e um relatório HTML de resumo.
Qual autenticação a API vai usar?
A API usará autenticação com API key via Bearer tokens. As API keys serão geradas a partir do dashboard do Crawlux. Cada API key é escopada a um workspace e tem rate limits configuráveis. Os callbacks de webhook serão autenticados via assinaturas HMAC-SHA256 usando um segredo compartilhado.
Haverá SDKs disponíveis?
Duas SDKs estão planejadas para o lançamento de Q4 2026. Uma SDK Node.js publicada no npm sob o nome de pacote crawlux-sdk. Uma SDK Python publicada no PyPI sob o nome de pacote crawlux. As duas SDKs fornecerão wrappers tipados em torno da API REST, além de helpers para padrões comuns como polling para conclusão de auditoria.
Quais limites de uso a API terá?
Os rate limits escalarão com o tier. Tier gratuito: 5 auditorias por mês. Tier Pro: 50 auditorias por mês. Tier Team: 200 auditorias por mês. Tier Enterprise (preços personalizados): auditorias ilimitadas com infraestrutura dedicada. Todos os tiers incluem chamadas ilimitadas de recuperação de resultados. Os callbacks de webhook contam separadamente e não têm rate-limit.
Como sou avisado quando a API for lançada?
Três formas. Primeiro, envie um email para [email protected] com o assunto API Waitlist para entrar na lista de acesso antecipado. Segundo, siga a página de changelog para atualizações de produto. Terceiro, rode uma auditoria gratuita e responda a qualquer um dos follow-ups por email confirmando interesse de desenvolvedor. O acesso antecipado abre aproximadamente 2 semanas antes do lançamento público da API.
Rode uma auditoria gratuita e baixe o JSON
A forma mais rápida de avaliar o JSON de auditoria para integração: rode uma auditoria real no seu próprio domínio e inspecione a saída. Primeira auditoria gratuita por domínio.
Saída JSON disponível · Webhooks disponíveis · API Q4 2026 · Acesso antecipado de 2 semanas