Autenticação, erros e limites da API

A API de integração do Sentrya vive em https://app.flowbix.com/api/v1/svc e é autenticada por um token de service account. Esta página reúne o que vale para todas as rotas: header, envelope de erro, códigos de status, formatos e paginação.

Endereço e autenticação

Toda rota desta API começa com https://app.flowbix.com/api/v1/svc. O token vai no header Authorization, no esquema Bearer:

curl -s https://app.flowbix.com/api/v1/svc/incidents/summary \
  -H "Authorization: Bearer svc_SEU_TOKEN"

O token identifica a empresa. Você nunca informa org_id em query, corpo ou header: o servidor resolve a empresa a partir do hash do token e isola todos os dados por ela. Um id de outra empresa em qualquer parâmetro simplesmente não casa nada.

Como obter o token: Service accounts: tokens de integração.

Envelope de erro

Toda resposta de erro é JSON com o campo error (texto em português) e, em alguns casos, um code estável para tratar por programa:

{"error": "token inválido"}

{"error": "limite do seu plano atingido", "code": "limit_reached", "limit_key": "max_service_accounts"}

Trate error como mensagem para humanos e decida a lógica pelo status HTTP (e por code, quando existir).

Códigos de status

Formatos

• Timestamps sempre em RFC 3339 e UTC, por exemplo "2026-08-26T14:03:11Z". Campos que podem não existir (resolved_at) vêm como null.
• Severidade é um inteiro de 0 a 5 na escala do Zabbix, acompanhado do rótulo severity_label: not_classified, info, warning, average, high, disaster. No app esses valores aparecem como Não classificado, Informação, Atenção, Média, Alta e Desastre (ver Severidades e estados).
• Ids são inteiros positivos. Listas de ids no corpo viajam como array JSON; na query, como CSV (severity=4,5) ou parâmetro repetido (hosts=a&hosts=b).
• Corpo das ações: JSON com Content-Type: application/json, até 8 KiB. Campos desconhecidos são ignorados.

Paginação

A listagem de incidentes usa limit e offset:

A resposta devolve o total para você saber quando parar:

{
  "incidents": [ … ],
  "pagination": { "limit": 100, "offset": 200, "total": 1342 }
}

Toda ordenação tem desempate por id, então paginar por offset não repete nem pula itens entre páginas, mesmo com a lista mudando.

Limites de uso

Não há limite por janela de tempo nas rotas /svc neste momento. Os limites em vigor são de tamanho e de lote:

Seja um bom vizinho: para acompanhar incidentes em tempo quase real, consulte a cada 30 a 60 segundos com sort=newest e lembre o maior id já visto. É o que o Sentrya Trigger do n8n faz.

Rotas disponíveis

O token svc_ é aceito só nestas oito rotas. Qualquer outra responde 401.

Para enviar alertas ao Sentrya não se usa o token svc_: o intake é POST /api/v1/alerts autenticado pelo token whk_ da fonte (ver Referência do payload).

Veja também

• Service accounts: tokens de integração
• Consultar incidentes pela API
• Reconhecer e dispensar pela API
• Exemplos de integração