Pular para o conteúdo principal

Visão geral da API

A API do RuleForge é uma API HTTP JSON que permite validar regras e decoders, rodar logtests, gerenciar projetos, versões e casos de teste, e automatizar integrações com pipelines de segurança — tudo o que você faz no produto pode ser feito programaticamente.

Este guia é para integradores — pessoas que estão escrevendo scripts de CI, ferramentas internas ou automações que usam o RuleForge em nome de uma organização.

Base URL​

A base de todos os endpoints é:

https://<seu-host>/api/v1

O host é definido pelo operador do RuleForge. Em ambientes locais de desenvolvimento o padrão é:

http://localhost:8000/api/v1

A variável de ambiente NATIVE_WAZUH_API_PUBLIC_BASE_URL controla esse valor no servidor. Se você é um consumidor da API, peça esse endereço ao time que mantém a sua instância.

Versionamento​

A API atual é v1, identificada pelo prefixo /api/v1 em toda requisição. A compatibilidade é mantida dentro de uma mesma major:

  • campos novos em respostas podem ser adicionados sem aviso;
  • enums podem receber novos valores — trate valores desconhecidos de forma tolerante;
  • remoções ou mudanças de sentido acontecem apenas em uma nova major (/api/v2).

Formato​

  • Request: Content-Type: application/json; charset=utf-8 para bodies. Alguns endpoints aceitam multipart/form-data quando documentado explicitamente.
  • Response: application/json; charset=utf-8, exceto SSE (text/event-stream) em /ai/stream e /notifications/stream.
  • Datas: todas em ISO 8601 UTC (2026-04-24T15:30:00Z).
  • IDs: strings opacas (UUID v4 na maioria dos casos). Não tente parsear.
  • Multi-tenant: cada organização é um tenant isolado. O header X-Org-Id identifica qual organização está no contexto quando uma chave ou usuário pertence a mais de uma.

Status codes​

FaixaSignificado
2xxSucesso. 200 para respostas com body, 201 para criações com body, 204 para sucessos sem body.
4xxErro do cliente — a requisição precisa ser corrigida antes de repetir.
5xxErro do servidor — pode ser tentado novamente com backoff.

Consulte Erros para o envelope de resposta e a tabela de códigos.

Autenticação​

A API suporta quatro formas de autenticação:

  1. API Keys (X-API-Key: rfk_…) — recomendada para integrações e automações.
  2. JWT Bearer — emitido no login, para uso em SPAs/servidores.
  3. Cookie de sessão — usado pelo navegador quando acessa o próprio RuleForge.
  4. OIDC/SSO — fluxo delegado a um provedor de identidade corporativa.

Detalhes em Autenticação.

Convenções transversais​

  • Headers padrão: X-Request-Id, Traceparent, X-Org-Id, x-locale.
  • Paginação por limit + offset ou cursor conforme o endpoint.
  • Rate limit global e por rota sensível — ver Limites e uso.
  • Payload máximo de 8 MB por requisição.

Veja Convenções para a referência completa.

O que não está coberto aqui​

Esta documentação cobre apenas o que é exposto ao cliente/integrador:

  • Endpoints de administração da plataforma (/platform/admin/*) são operações internas do operador da instância. Eles exigem sessão de platform admin e não funcionam com API keys comuns. Não estão documentados aqui.
  • SCIM (/scim/v2/*) é um canal de provisionamento usado por IdPs corporativos (Okta, Entra ID). A documentação operacional está em Provisionamento SCIM.
  • Webhook da Stripe (/billing/webhooks/stripe) é chamado pela Stripe, não pelo cliente.

Documentação interativa (Swagger)​

A especificação OpenAPI é gerada automaticamente pelo backend e, quando habilitada, fica disponível em:

  • GET /openapi.json — spec crua
  • GET /docs — Swagger UI
  • GET /redoc — ReDoc

A variável de ambiente NATIVE_WAZUH_DOCS_EXPOSURE controla quem pode acessar:

ValorComportamento
off (padrão)Todas as rotas de docs retornam 404.
adminRotas exigem sessão de platform admin.
publicAberto — adequado apenas para ambientes de desenvolvimento.

Em produção o padrão é off. Use este guia como a fonte canônica.

Próximos passos​