API¶

Objetivo¶

Usar a API do RR Flow para integrar sistemas externos, automatizar listas, consultar conexões, localizar arquivos nfcapd, ler logs de CGNAT e consumir séries temporais de tráfego.

Como acessar¶

URL base: use o mesmo host do RR Flow, por exemplo https://rrflow.seudominio.com.
Autenticação: prefira o cabeçalho Authorization: Bearer <token>.
Alternativa suportada: X-API-Token: <token>.
Onde configurar o token: em Configurações > Sistema.

Exemplo base:

export RR_URL="https://rrflow.seudominio.com"
export RR_TOKEN="SEU_TOKEN"

Formatos aceitos¶

source: use exatamente o nome da fonte cadastrada em Operação > Fontes.
start e stop: aceitam:
- 2026-03-12 10:00
- 2026-03-12 10:00:00
- 2026-03-12T10:00:00
- epoch em segundos
- epoch em milissegundos
Janela relativa: nas rotas de consulta baseadas em arquivos, você também pode usar window_sec, window_seconds, range_sec ou relative_sec em vez de start e stop.

Observações importantes¶

Se o token da API estiver habilitado, ele passa a ser obrigatório para chamadas externas.
Nas rotas de alteração de whitelist e blacklist, o token precisa estar configurado e é sempre exigido.
Em consultas pesadas, chamadas paralelas do mesmo cliente podem invalidar a requisição anterior. - Se você precisar rodar várias consultas ao mesmo tempo, envie X-Client-Key diferente em cada uma.
IDs de grupos e serviços podem ser obtidos exportando os cadastros pelas telas do sistema ou usando o testador interno em Outros > API.

Endpoints¶

POST `/api/add-blacklist`¶

O que faz¶

Adiciona um IP ou prefixo na blacklist.

Parâmetros¶

target: obrigatório. IP ou prefixo CIDR.
- Se você enviar um host sem máscara, o RR Flow normaliza para /32 em IPv4 ou /128 em IPv6.
group_id: opcional. ID do grupo de blacklist que deve receber a entrada.
- Pode ser repetido mais de uma vez.
direction: opcional. source, destination ou both.
- Só é usado quando o sistema precisa criar o grupo técnico API External.

Exemplo¶

curl -X POST "$RR_URL/api/add-blacklist" \
  -H "Authorization: Bearer $RR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "203.0.113.45",
    "direction": "both"
  }'

Resposta esperada¶

status=success: entrada adicionada.
status=permitted: a entrada já existia.
Campos mais comuns:
- list
- action
- target
- affected_groups
- changed_groups

Observações¶

Se group_id não for informado, o sistema tenta aplicar nos grupos de blacklist já usados por regras de FlowSpec.
Se não existir grupo em uso, o RR Flow usa ou cria o grupo API External.

POST `/api/add-whitelist`¶

O que faz¶

Adiciona um IP ou prefixo na whitelist.

Parâmetros¶

target: obrigatório. IP ou prefixo CIDR. - Se você enviar um host sem máscara, o RR Flow normaliza para /32 em IPv4 ou /128 em IPv6.
group_id: opcional. ID do grupo de whitelist. - Pode ser repetido.
direction: opcional. source, destination ou both. - Só é usado quando o grupo técnico API External precisa ser criado.

Exemplo¶

curl -X POST "$RR_URL/api/add-whitelist" \
  -H "Authorization: Bearer $RR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "198.51.100.0/24"
  }'

Resposta esperada¶

status=success: entrada adicionada.
status=permitted: a entrada já existia.
Campos mais comuns:
- list
- action
- target
- affected_groups
- changed_groups

Observações¶

Quando group_id não é enviado, a whitelist usa ou cria o grupo técnico API External.

GET `/api/cgnat-logs`¶

O que faz¶

Consulta logs de CGNAT a partir de uma fonte configurada com CGNAT.

Parâmetros¶

source: obrigatório.
type: obrigatório. public ou private.
ip: opcional. Filtra um IP específico.
port: opcional. Filtra uma porta específica.
limit: opcional. Quantidade máxima de linhas.
- O sistema limita o valor entre 1 e 500.
start, stop: opcionais.
- Se omitidos, o padrão é os últimos 5 minutos.

Exemplo¶

curl -G "$RR_URL/api/cgnat-logs" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "type=public" \
  --data-urlencode "ip=200.160.2.10" \
  --data-urlencode "port=443" \
  --data-urlencode "limit=20"

Resposta esperada¶

meta: traz source, mode, start, stop, type, ip, port, limit e range.
mode: indica o modo da fonte, por exemplo pba, dynamic ou deterministic.
rows: lista os eventos encontrados.
Em fontes pba, as linhas costumam trazer:
- allocated
- event
- status
- proto
- ip
- nat_ip
- start
- end
- total
- pba_blocks
Em fontes dynamic ou deterministic, as linhas costumam trazer:
- allocated
- event
- proto
- src_ip, src_port
- dst_ip, dst_port
- x_src_ip, x_src_port
- x_dst_ip, x_dst_port

Observações¶

A fonte precisa estar marcada como CGNAT em Operação > Fontes.
Se a fonte não tiver CGNAT habilitado, a API retorna erro.

POST `/api/del-blacklist`¶

O que faz¶

Remove um IP ou prefixo da blacklist por correspondência exata.

Parâmetros¶

target: obrigatório.
group_id: opcional.
- Se for omitido, o RR Flow procura em todos os grupos de blacklist.

Exemplo¶

curl -X POST "$RR_URL/api/del-blacklist" \
  -H "Authorization: Bearer $RR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "203.0.113.45/32"
  }'

Resposta esperada¶

status=success: entrada removida.
status=permitted: a entrada não foi encontrada.

Observações¶

A remoção é exata. - Exemplo: remover 203.0.113.45/32 não remove 203.0.113.0/24.

POST `/api/del-whitelist`¶

O que faz¶

Remove um IP ou prefixo da whitelist por correspondência exata.

Parâmetros¶

target: obrigatório.
group_id: opcional.
- Se for omitido, o RR Flow procura em todos os grupos de whitelist.

Exemplo¶

curl -X POST "$RR_URL/api/del-whitelist" \
  -H "Authorization: Bearer $RR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "198.51.100.0/24"
  }'

Resposta esperada¶

status=success: entrada removida.
status=permitted: a entrada não foi encontrada.

GET `/api/list-connections`¶

O que faz¶

Executa nfdump e retorna conexões em JSON. É a rota mais flexível para consumo externo quando você precisa de linhas detalhadas, não só séries temporais.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
order: opcional.
- flows
- bytes
- obyte
- packets
- opkg
- pps
- opps
- bps
- obps
- bpp
- obpp
- duration
limit: opcional. Máximo de linhas retornadas.
top: opcional. Quantidade usada no bloco stats.
agg: opcional. Agrega o resultado.
- Pode ser repetido ou enviado separado por vírgula.
- Valores aceitos:
  - proto
  - flags
  - srcip
  - dstip
  - srcnet
  - dstnet
  - srcnet,dstnet
  - srcport
  - dstport
  - srcas
  - dstas
  - inif
  - outif
  - bgpnext
  - insrcmac
  - outdstmac
  - indstmac
  - outsrcmac
filter: opcional. Expressão do nfdump.
cgnatmap: opcional.
- Use 1 para aplicar o mapeamento determinístico de CGNAT definido em Meu ISP.

Exemplo¶

curl -G "$RR_URL/api/list-connections" \
  -H "Authorization: Bearer $RR_TOKEN" \
  -H "X-Client-Key: conexoes-top" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "order=bytes" \
  --data-urlencode "limit=20" \
  --data-urlencode "filter=(in if 169) and proto tcp"

Exemplo com agregação¶

curl -G "$RR_URL/api/list-connections" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=1800" \
  --data-urlencode "agg=srcip,dstip" \
  --data-urlencode "order=bytes" \
  --data-urlencode "top=10"

Resposta esperada¶

meta: contexto da consulta.
columns: nomes das colunas efetivamente retornadas.
rows: linhas da consulta.
stats: resumo pré-agregado por bytes.

Observações¶

O formato de rows muda conforme agg.
Para filtros complexos, use --data-urlencode no curl.

GET `/api/list-files`¶

O que faz¶

Lista os arquivos nfcapd existentes para uma fonte em um intervalo de tempo.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
window_sec, window_seconds, range_sec, relative_sec: opcionais.
- São atalhos de janela relativa.

Exemplo¶

curl -G "$RR_URL/api/list-files" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600"

Resposta esperada¶

O bloco data costuma trazer:
- source
- start
- stop
- rounded_start
- rounded_stop
- interval_minutes
- first_file
- last_file
- range
- count
- truncated
- files

Observações¶

Essa rota também existe como alias legado em /api/demo-files.
É útil para validar se a janela consultada realmente possui arquivos antes de chamar outras rotas.

GET `/api/traffic-as`¶

O que faz¶

Retorna tráfego por ASN ao longo do tempo.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
direction: rx, tx ou both.
order: usa o mesmo conjunto de ordenação das outras rotas de tráfego.
filter: expressão do nfdump.
group_type: opcional.
- Nome do arquivo JSON de grupos, sem extensão.
group_ids: opcional.
- IDs separados por vírgula.
group_id: opcional.
- Alternativa repetível para group_ids.
top: opcional.
- Só é usado quando você quer a lista bruta de ASNs, sem grupos.
max_points: opcional.
timeout: opcional.

Exemplo com lista bruta¶

curl -G "$RR_URL/api/traffic-as" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "direction=rx" \
  --data-urlencode "top=10"

Exemplo com grupos¶

curl -G "$RR_URL/api/traffic-as" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "group_type=as_fav" \
  --data-urlencode "group_ids=<id-grupo-1>,<id-grupo-2>"

Resposta esperada¶

labels: eixo do tempo.
series: séries por direção e por grupo ou ASN.
totals: somatórios.
meta: contexto da consulta.

GET `/api/traffic-flags`¶

O que faz¶

Retorna tráfego por flags TCP ao longo do tempo.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
direction: rx, tx ou both.
order: ordenação.
filter: expressão do nfdump.
max_points: opcional.
timeout: opcional.

Exemplo¶

curl -G "$RR_URL/api/traffic-flags" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=1800" \
  --data-urlencode "direction=both" \
  --data-urlencode "filter=proto tcp"

Resposta esperada¶

series: séries como SYN, ACK, SYN+ACK, RST e similares.
labels: eixo do tempo.
totals: totais por série.

GET `/api/traffic-geo`¶

O que faz¶

Retorna tráfego por país ao longo do tempo.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
direction: rx, tx ou both.
order: ordenação.
filter: expressão do nfdump.
top: opcional.
- Mantém só os principais países.
max_points: opcional.
timeout: opcional.

Exemplo¶

curl -G "$RR_URL/api/traffic-geo" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=7200" \
  --data-urlencode "direction=rx" \
  --data-urlencode "top=10" \
  --data-urlencode "filter=(in if 169) and any"

Resposta esperada¶

series: séries por país.
totals: totais por país.
meta.top: valor aplicado na consulta.

GET `/api/traffic-interfaces`¶

O que faz¶

Retorna tráfego por interface ao longo do tempo.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
direction: rx, tx ou both.
order: ordenação.
filter: expressão do nfdump.
top: opcional.
- Mantém só as principais interfaces.
max_points: opcional.
timeout: opcional.

Exemplo¶

curl -G "$RR_URL/api/traffic-interfaces" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "direction=both" \
  --data-urlencode "top=5"

Resposta esperada¶

series: séries por interface.
labels: timestamps baseados nos arquivos nfcapd.
totals: somatório por interface.

GET `/api/traffic-prefixes`¶

O que faz¶

Retorna tráfego por grupos de prefixos ao longo do tempo.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
direction: rx, tx ou both.
order: ordenação.
filter: expressão do nfdump.
group_type: obrigatório.
- Nome do cadastro exportado em JSON, sem extensão.
- Exemplo comum: cdns.
group_ids: obrigatório.
- IDs separados por vírgula.
group_id: opcional.
- Alternativa repetível.
max_points: opcional.
timeout: opcional.

Exemplo¶

curl -G "$RR_URL/api/traffic-prefixes" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "direction=tx" \
  --data-urlencode "group_type=cdns" \
  --data-urlencode "group_ids=<id-globo>,<id-google>"

Resposta esperada¶

series: séries por grupo consultado.
meta.group_type: origem do catálogo usado.
meta.group_ids: grupos aplicados.

GET `/api/traffic-proto`¶

O que faz¶

Retorna tráfego por protocolo ao longo do tempo.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
direction: rx, tx ou both.
order: ordenação.
filter: expressão do nfdump.
max_points: opcional.
timeout: opcional.

Exemplo¶

curl -G "$RR_URL/api/traffic-proto" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "direction=both"

Resposta esperada¶

series: séries por protocolo, por exemplo TCP, UDP, ICMP.
totals: totais por protocolo.

GET `/api/traffic-services`¶

O que faz¶

Retorna tráfego por serviços cadastrados em Operação > Serviços.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
direction: rx, tx ou both.
order: ordenação.
filter: expressão do nfdump.
group_ids: obrigatório.
- UUIDs dos serviços separados por vírgula.
group_id: opcional.
- Alternativa repetível.
max_points: opcional.
timeout: opcional.

Exemplo¶

curl -G "$RR_URL/api/traffic-services" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "group_ids=<uuid-http>,<uuid-dns>"

Resposta esperada¶

series: séries por serviço.
meta.group_ids: serviços efetivamente usados.

GET `/api/traffic-subnet`¶

O que faz¶

Retorna tráfego agrupado por sub-redes.

Parâmetros¶

source: obrigatório.
start, stop: opcionais.
family: obrigatório. ipv4 ou ipv6.
mask: opcional.
- IPv4: 1 a 32
- IPv6: 1 a 128
- Padrão em IPv4: 24
- Padrão em IPv6: 34
direction: rx, tx ou both.
agg: opcional. src ou dst.
agg_rx: opcional. Lado da agregação para RX.
agg_tx: opcional. Lado da agregação para TX.
order: ordenação.
filter: expressão do nfdump.
top: opcional.
- Mantém só as principais sub-redes.
max_points: opcional.
timeout: opcional.

Exemplo IPv4¶

curl -G "$RR_URL/api/traffic-subnet" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "family=ipv4" \
  --data-urlencode "mask=24" \
  --data-urlencode "direction=rx" \
  --data-urlencode "agg=src" \
  --data-urlencode "top=10"

Exemplo IPv6¶

curl -G "$RR_URL/api/traffic-subnet" \
  -H "Authorization: Bearer $RR_TOKEN" \
  --data-urlencode "source=BORDA-RS" \
  --data-urlencode "window_sec=3600" \
  --data-urlencode "family=ipv6" \
  --data-urlencode "mask=48" \
  --data-urlencode "direction=both" \
  --data-urlencode "agg_rx=src" \
  --data-urlencode "agg_tx=dst"

Resposta esperada¶

series: séries por bucket de sub-rede.
meta.family: família consultada.
meta.mask: máscara aplicada.
meta.agg, meta.agg_rx, meta.agg_tx: lado da agregação.

Problemas comuns¶

401 Unauthorized: token ausente, inválido ou não enviado no cabeçalho correto.
503 API token is not configured: rota de mutação chamada antes de configurar o token da API.
source is required ou invalid source: nome da fonte não corresponde ao cadastro em Operação > Fontes.
group_type is required, group_id is required ou grupos vazios: faltou informar o catálogo ou os IDs esperados pela rota.
filter too long: a expressão enviada passou do limite aceito.
409 cancelled: uma consulta mais nova substituiu a anterior.
- Para rodar em paralelo, envie X-Client-Key diferente em cada chamada.
Retorno status=permitted nas rotas de lista: a API entendeu a chamada, mas não precisou alterar nada.
- Exemplo: item já existia ao adicionar.
- Exemplo: item não existia ao remover.

API¶

Objetivo¶

Como acessar¶

Formatos aceitos¶

Observações importantes¶

Endpoints¶

POST /api/add-blacklist¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

Observações¶

POST /api/add-whitelist¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

Observações¶

GET /api/cgnat-logs¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

Observações¶

POST /api/del-blacklist¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

Observações¶

POST /api/del-whitelist¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

GET /api/list-connections¶

O que faz¶

Parâmetros¶

Exemplo¶

Exemplo com agregação¶

Resposta esperada¶

Observações¶

GET /api/list-files¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

Observações¶

GET /api/traffic-as¶

O que faz¶

Parâmetros¶

Exemplo com lista bruta¶

Exemplo com grupos¶

Resposta esperada¶

GET /api/traffic-flags¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

GET /api/traffic-geo¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

GET /api/traffic-interfaces¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

GET /api/traffic-prefixes¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

GET /api/traffic-proto¶

O que faz¶

Parâmetros¶

Exemplo¶

Resposta esperada¶

GET /api/traffic-services¶

POST `/api/add-blacklist`¶

POST `/api/add-whitelist`¶

GET `/api/cgnat-logs`¶

POST `/api/del-blacklist`¶

POST `/api/del-whitelist`¶

GET `/api/list-connections`¶

GET `/api/list-files`¶

GET `/api/traffic-as`¶

GET `/api/traffic-flags`¶

GET `/api/traffic-geo`¶

GET `/api/traffic-interfaces`¶

GET `/api/traffic-prefixes`¶

GET `/api/traffic-proto`¶

GET `/api/traffic-services`¶

GET `/api/traffic-subnet`¶