API do CentralOps
Tudo que o console faz, a API faz. A interface web não tem atalho privado: ela autentica e chama exatamente os mesmos endpoints que você chama de um script.
Esta seção é para quem tem um token na mão (ou vai criar um) e quer automatizar alguma coisa.
Quando usar
- Monitoramento externo. Um Zabbix, um Grafana ou um script de plantão que pergunta de tempos em tempos se a coleta está em dia e se a entrega está de pé.
- Automação de operação. Destravar um coletor parado, reprocessar eventos em quarentena, disparar uma recoleta depois de corrigir um mapping.
- Ingestão por push. Mandar eventos de uma fonte que o CentralOps ainda não coleta sozinho.
- Inventário e auditoria. Exportar o que está configurado, quem mudou o quê e quando.
Endereço base
Quase todos os endpoints ficam sob /api, no mesmo host do console:
https://centralops.example.com/api
Não existe subdomínio separado nem porta diferente para a API. Se o console abre em https://centralops.example.com, a API responde em https://centralops.example.com/api.
As exceções ficam na raiz, fora do /api: /livez e /readyz, que são as sondas de saúde, públicas e sem token. São elas que você aponta num balanceador ou num healthcheck de contêiner.
Só a gestão de tokens e de contas de serviço vive sob /api/v1 (12 operações). Todo o resto responde direto em /api, sem número de versão no caminho.
Ou seja: /api/v1/tokens existe, mas /api/v1/integrations não. É /api/integrations. Quando estiver montando URLs, siga a referência em vez de assumir que /v1 vale para tudo.
Dois tipos de token, e eles não se substituem
Esta é a confusão mais comum, e ela custa tempo porque o erro que ela produz é um 401 seco, sem explicação.
| Token de gestão | Token de ingestão | |
|---|---|---|
| Formato | copsk_... | coi_<id da integração>_... |
| Serve para | Ler e operar a plataforma inteira | Só empurrar eventos para dentro |
| Representa | Uma pessoa ou uma conta de serviço | Uma integração específica |
| Respeita papel e permissão? | Sim | Não se aplica |
| Onde nasce | Perfil do usuário, ou contas de serviço | Na própria integração de push |
| Usado em | Todos os endpoints desta seção | Só POST /api/ingest/{stream} |
Um token copsk_ não autentica no envio de eventos, e um token coi_ não lista integração nenhuma. Se você recebeu 401 num endpoint que jurava estar certo, confira antes de tudo qual das duas famílias está no header.
Repare que o caminho de envio exige o segmento do fluxo: é POST /api/ingest/{stream}, não POST /api/ingest. Os endpoints que gerenciam o token de ingestão ficam sob /api/ingest/integrations/{id}/token e usam o token de gestão, como o resto da API.
A ingestão por push tem documentação própria em Ingestão por push. O resto desta seção trata do token de gestão.
O modelo mental do sistema
A API espelha o caminho que um evento percorre. Saber o caminho ajuda a achar o endpoint certo sem procurar na lista inteira:
- Integração puxa (ou recebe) eventos de um fornecedor. Sophos, Wazuh, CrowdStrike, Defender e afins.
- Mapping normaliza o evento cru para OCSF, o formato canônico.
- Enriquecimento acrescenta contexto ao evento já normalizado.
- Rota decide para onde ele vai.
- Destino entrega. SIEM, data lake, syslog.
Quando alguma coisa não chega ao destino, o problema está em um desses cinco pontos, e existe um grupo de endpoints para inspecionar cada um. A referência está organizada nessa ordem.
Duas caixas de escape completam o desenho:
- Quarentena: evento que a normalização recusou.
- DLQ: evento normalizado que o destino recusou.
Formato
Requisição e resposta são JSON. Mande Content-Type: application/json em tudo que tenha corpo.
Alguns poucos endpoints de exportação devolvem CSV ou NDJSON.
Os endpoints que devolvem CSV ou NDJSON aparecem no esquema como application/json, porque o tipo real é definido na resposta e não na declaração da rota.
Isso quebra cliente gerado automaticamente: ele tenta interpretar CSV como JSON e falha. Se a sua automação baixa export, trate esses endpoints à mão em vez de pelo cliente gerado.
Por onde começar
- Autenticação: criar o token, usar no header, entender o que acontece quando ele expira.
- Permissões e escopo: decidir qual papel e quais scopes o token precisa. Vale a leitura antes de criar, porque um token nasce com o poder do dono se você não restringir.
- Convenções: paginação, formato de erro, datas. O que vale para todo endpoint.
- Referência: o mapa completo, por família.
- Receitas: tarefas prontas, com
curl, para os casos mais pedidos.
A aplicação gera um esquema OpenAPI a partir do próprio código. Ele é a fonte que nunca fica desatualizada.
Um aviso para poupar tempo: pelo endereço público ele não responde, porque o nginx da stack bloqueia /openapi.json e /docs na borda. Esquema OpenAPI mostra como pegá-lo mesmo assim e o que ajustar antes de gerar um cliente.