Skip to main content

API overview

The RuleForge API is an HTTP JSON API that lets you validate rules and decoders, run logtests, manage projects, versions and test cases, and automate integrations with security pipelines — everything you do in the product can be done programmatically.

This guide is for integrators — people writing CI scripts, internal tools or automations that use RuleForge on behalf of an organization.

Base URL​

All endpoints live under:

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

The host is set by whoever operates RuleForge. In local development the default is:

http://localhost:8000/api/v1

The NATIVE_WAZUH_API_PUBLIC_BASE_URL environment variable controls this value on the server. If you are an API consumer, ask the team maintaining your instance for this address.

Versioning​

The current API is v1, identified by the /api/v1 prefix on every request. Compatibility is kept within a major version:

  • new fields may be added to responses without notice;
  • enums may receive new values — handle unknown values tolerantly;
  • removals or semantic changes only happen in a new major (/api/v2).

Format​

  • Request: Content-Type: application/json; charset=utf-8 for bodies. A few endpoints accept multipart/form-data when explicitly documented.
  • Response: application/json; charset=utf-8, except SSE (text/event-stream) on /ai/stream and /notifications/stream.
  • Dates: all ISO 8601 UTC (2026-04-24T15:30:00Z).
  • IDs: opaque strings (UUID v4 in most cases). Don't try to parse them.
  • Multi-tenant: each organization is an isolated tenant. The X-Org-Id header tells which organization is in context when a key or user belongs to more than one.

Status codes​

RangeMeaning
2xxSuccess. 200 for responses with body, 201 for creations with body, 204 for success without body.
4xxClient error — the request must be fixed before retrying.
5xxServer error — may be retried with backoff.

See Errors for the response envelope and the code table.

Authentication​

The API supports four authentication methods:

  1. API keys (X-API-Key: rfk_…) — recommended for integrations and automations.
  2. JWT Bearer — issued at login, meant for SPAs/servers.
  3. Session cookie — used by the browser when accessing RuleForge itself.
  4. OIDC/SSO — flow delegated to a corporate identity provider.

Details in Authentication.

Cross-cutting conventions​

  • Standard headers: X-Request-Id, Traceparent, X-Org-Id, x-locale.
  • Pagination via limit + offset or cursor depending on the endpoint.
  • Global and per-sensitive-route rate limiting — see Limits and usage.
  • Max 8 MB per request payload.

See Conventions for the full reference.

What is not covered here​

This documentation only covers what is exposed to clients/integrators:

  • Platform-admin endpoints (/platform/admin/*) are internal operations for the instance operator. They require a platform admin session and do not work with regular API keys. Not documented here.
  • SCIM (/scim/v2/*) is a provisioning channel used by corporate IdPs (Okta, Entra ID). Operational documentation is at SCIM provisioning.
  • Stripe webhook (/billing/webhooks/stripe) is called by Stripe, not by the client.

Interactive documentation (Swagger)​

The OpenAPI spec is automatically generated by the backend and, when enabled, is served at:

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

The NATIVE_WAZUH_DOCS_EXPOSURE environment variable controls access:

ValueBehavior
off (default)All doc routes return 404.
adminRoutes require a platform admin session.
publicOpen — suitable only for development environments.

In production the default is off. Use this guide as the canonical source.

Next steps​