Crawlux for developers and platforms.
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 acceso temprano
The API ships Q4 2026 but early access opens roughly 2 weeks before public launch. Email [email protected] with subject "API Waitlist" to join. Early access is free and includes API documentation review.
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.
Garantías de entrega de webhooks
Crawlux retries webhook delivery up to 5 times over 24 hours if your endpoint returns non-2xx status. Always return a 2xx status quickly (under 5 seconds) and process the payload asynchronously.
Endpoints API planeados
The Crawlux REST API ships Q4 2026. Below: the planned endpoint surface. Subject to refinement during the early access period. Base URL: 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/jsonAPI keys come in two environments: crl_test_ for sandbox testing without consuming audit quota and crl_live_ for production audits that consume tier quota. Webhook signatures use a separate signing secret configured per webhook.
O modo de teste é gratuito
Test mode keys (crl_test_) return realistic but synthetic audit data without consuming quota. Useful for building integrations without paying for real audits during development.
Rate limits
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.
| Tier | Audits / month | Result retrieval | Use case |
|---|---|---|---|
| Free | 5 | Unlimited | Personal projects, evaluation, single-domain teams |
| Pro | 50 | Unlimited | Voltado para agências, líderes de SEO internos, consultores multi-projeto |
| Team | 200 | Unlimited | Marketing agencies, multi-tenant platforms, larger SEO teams |
| Enterprise | Custom | Unlimited | Dedicated infrastructure, SLA, custom integration support |
Rate limit headers are returned on every API response. X-RateLimit-Limit shows your tier limit. X-RateLimit-Remaining shows audits remaining. X-RateLimit-Reset is the Unix timestamp when the limit resets (start of next month).
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 de plataforma 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.
Monitoreo masivo de dominios
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 desarrolladores
Seis perguntas cobrindo o roadmap da API, saída JSON, autenticação, SDKs e rate limits.
When does the Crawlux API ship?
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.
Can I get audit JSON output today?
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.
What authentication will the API use?
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.
Will SDKs be available?
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.
What rate limits will the API have?
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.
How can I get notified when the API ships?
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.
JSON output live · Webhooks live · API Q4 2026 · 2-week early access window