API Reference
A API do Heimdall oferece acesso programático ao maior grafo de dados públicos do Brasil. Consulte entidades, explore conexões, monitore red flags e faça perguntas em linguagem natural.
Endpoints REST com documentação completa
Autenticação via API Key no header
Todas as respostas em formato JSON
Autenticação
Todas as requisições à API devem incluir um header Authorization com seu Bearer Token. Obtenha sua API Key no dashboard após criar uma conta.
# Inclua o header em todas as requisições
curl -H "Authorization: Bearer hmdl_sk_1a2b3c4d5e6f7g8h9i0j" \
"https://api.heimdall.parsebots.com/v1/entities/12345678000190"
# Teste sua conexão
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.heimdall.parsebots.com/v1/status"
# Resposta esperada:
# { "status": "ok", "plan": "developer", "requests_remaining": 9847 }Importante: Nunca exponha sua API Key no frontend. Use variáveis de ambiente e faça as chamadas pelo backend da sua aplicação.
Busca de Entidades
Busque e recupere informações detalhadas sobre pessoas, empresas, órgãos e contratos.
Grafo de Conexões
Explore o grafo de relacionamentos entre entidades. Ideal para visualizações e análises de rede.
Red Flags
Acesse os alertas de irregularidades detectados automaticamente pelo motor de IA.
Monitoramento em Tempo Real
Crie monitores para receber notificações via webhook quando red flags forem detectados.
Consulta Natural (IA)
Faça perguntas em português sobre o grafo. O sistema traduz para Cypher usando LLMs e retorna resultados estruturados.
Exemplos de perguntas
SDKs & Bibliotecas
Bibliotecas oficiais para integrar o Heimdall na sua aplicação.
pip install heimdall-sdknpm install @heimdall/sdkgo get github.com/heimdall-io/sdk-goMaven: io.heimdall:sdk:1.0.0Exemplo rápido — Python
from heimdall import HeimdallClient
# Inicializar o cliente
client = HeimdallClient(api_key="hmdl_sk_your_key")
# Buscar uma empresa pelo CNPJ
entity = client.entities.get("12345678000190", depth=2)
print(f"Empresa: {entity.name}")
print(f"Score de risco: {entity.risk_score}")
print(f"Conexões: {entity.relations_count}")
# Explorar o grafo de conexões
graph = client.graph.get(
entity_id="12345678000190",
depth=2,
min_risk=0.5
)
for node in graph.nodes:
print(f" {node.type}: {node.label} (risco: {node.risk_score})")
# Consulta em linguagem natural
result = client.query.natural(
question="Quais sócios desta empresa são servidores públicos?"
)
print(f"Resposta: {result.answer}")
print(f"Confiança: {result.confidence}")
# Criar monitor de red flags
monitor = client.monitors.create(
entities=["12345678000190"],
webhook_url="https://minha-app.com/webhook",
severity_min="high"
)
print(f"Monitor ativo: {monitor.id}")Exemplo rápido — Node.js
import { Heimdall } from '@heimdall/sdk';
// Inicializar o cliente
const client = new Heimdall({ apiKey: 'hmdl_sk_your_key' });
// Buscar entidade
const entity = await client.entities.get('12345678000190', {
depth: 2,
include: ['relations', 'flags']
});
console.log(`Empresa: ${entity.name}`);
console.log(`Risco: ${entity.risk_score}`);
// Consulta natural com IA
const result = await client.query.natural({
question: 'Quais contratos desta empresa tiveram sobrepreço?'
});
console.log(result.answer);
// Monitorar red flags via webhook
const monitor = await client.monitors.create({
entities: ['12345678000190'],
webhookUrl: 'https://minha-app.com/webhook',
severityMin: 'high'
});