Dois canos: registros para fora, logs para dentro.

Conector de BI

POST /bi/records retorna registros achatados de um intervalo de datas, de uma de duas tabelas — mentions ou sources — agrupados pelas dimensões que você passar. Atrás da flag bi_connector.

POST https://app.bementioned.ai/api/v1/projects/{project_id}/bi/records

{
  "start_date": "2026-07-01",
  "end_date": "2026-07-31",
  "table": "mentions",
  "dimensions": ["week", "brand_id", "model_channel_id"],
  "limit": 10000,
  "offset": 0
}

As dimensões são um conjunto fechado, com no máximo um grão de tempo por requisição:

date · week · month · model_channel_id · country_code · prompt_id · topic_id · tag_id · brand_id · domain · url · source_type

As linhas carregam só componentes aditivos — contagens, e somas ao lado das suas contagens — e nenhuma razão, de propósito: some os componentes na sua ferramenta de BI e divida uma vez, e o agregado é exato em qualquer agrupamento.

Um aviso que vale ler duas vezes: scope_response_count é o denominador da linha e se repete idêntico entre linhas irmãs de um mesmo escopo — nunca some entre marcas, domínios ou URLs. E source_type é sempre separado e ecoado em cada linha: api e web_scrape nunca são misturados.

Webhook de ingest — agent analytics

Envie os access logs do seu CDN ou servidor e o produto os transforma em visitas de agent analytics: quais crawlers de IA leram quais páginas. O token é cunhado quando você cria uma fonte de ingest no app — prefixo bmi_, mostrado uma vez, rotacionável.

curl -X POST https://app.bementioned.ai/api/v1/ingest/agent-logs \
  -H "X-Ingest-Token: bmi_your_token_here" \
  --data-binary @access-log-batch.csv

O endpoint guarda o payload verbatim e responde 202 com um recibo — linhas mantidas, e linhas descartadas por motivo:

{
  "batch_id": 118,
  "line_count": 5000,
  "kept_count": 4816,
  "dropped": { "no_ua_match": 121, "ip_spoof": 12, "malformed": 51 }
}

Limites: 25 MiB por lote, 600 lotes por minuto por fonte, e um bucket estrito de credencial inválida. 401 para token ausente ou revogado, 403 para fonte pausada, 413 acima do teto de tamanho, 429 com Retry-After.

Esta superfície não carrega plan flag nem o limite de serving: a captura nunca para por motivo de plano. As linhas são interpretadas pelo formato declarado da fonte; alegações de bot não verificáveis são descartadas e contabilizadas no recibo.