API Reference

All API endpoints are served on the admin listener (127.0.0.1:9443 by default). Authenticated endpoints require a valid session cookie (kwaf_session) and CSRF token.

Setup

Method	Path	Description
`GET`	`/api/v1/setup/status`	Check if initial setup has been completed
`POST`	`/api/v1/setup/init`	Create the first admin user and optionally configure SMTP

Authentication

Method	Path	Description
`POST`	`/api/v1/auth/login`	Authenticate with username and password
`POST`	`/api/v1/auth/logout`	Destroy the current session
`POST`	`/api/v1/auth/magic-link`	Request a passwordless login email
`GET`	`/api/v1/auth/verify`	Verify a magic link token and create a session

Proxy Hosts

Method	Path	Description
`GET`	`/api/v1/hosts`	List all proxy hosts
`POST`	`/api/v1/hosts`	Create a new proxy host
`GET`	`/api/v1/hosts/{id}`	Get a proxy host by ID
`PUT`	`/api/v1/hosts/{id}`	Update a proxy host
`DELETE`	`/api/v1/hosts/{id}`	Delete a proxy host

WAF Rules

Method	Path	Description
`GET`	`/api/v1/rules`	List all WAF rules (filterable by `host_id`)
`POST`	`/api/v1/rules`	Create a custom WAF rule
`GET`	`/api/v1/rules/{id}`	Get a WAF rule by ID
`PUT`	`/api/v1/rules/{id}`	Update a WAF rule
`DELETE`	`/api/v1/rules/{id}`	Delete a WAF rule
`POST`	`/api/v1/rules/import`	Bulk import rules from JSON or YAML file (multipart, max 4 MB)
`POST`	`/api/v1/rules/test`	Test a single rule against a crafted request
`POST`	`/api/v1/rules/test-all`	Test a crafted request against all enabled rules

Certificates

Method	Path	Description
`GET`	`/api/v1/certificates`	List all stored certificates (domains, source, issuer, expiry)
`POST`	`/api/v1/certificates`	Upload a custom certificate (PEM cert + key)
`DELETE`	`/api/v1/certificates/{id}`	Delete a certificate (fails if assigned to a host)
`POST`	`/api/v1/certificates/cloudflare-origin`	Request a Cloudflare Origin CA certificate
`POST`	`/api/v1/certificates/cloudflare-edge`	Order a Cloudflare Edge certificate
`GET`	`/api/v1/settings/admin-trust-bundle`	Download the local CA trust bundle (ZIP)

Access Lists

Method	Path	Description
`GET`	`/api/v1/access-lists`	List all access lists
`POST`	`/api/v1/access-lists`	Create a new access list
`GET`	`/api/v1/access-lists/{id}`	Get an access list by ID
`PUT`	`/api/v1/access-lists/{id}`	Update an access list
`DELETE`	`/api/v1/access-lists/{id}`	Delete an access list
`POST`	`/api/v1/access-lists/azure-directory/search`	Search Azure AD users/groups via Microsoft Graph
`POST`	`/api/v1/access-lists/ad/test`	Test Active Directory LDAP connection
`POST`	`/api/v1/access-lists/ad/search`	Search Active Directory users/groups

Traffic & Analytics

Method	Path	Description
`GET`	`/api/v1/traffic`	Query request logs with filters (host, IP, status, action, time range)
`GET`	`/api/v1/analytics/top-ips`	Top source IPs by request and block count
`GET`	`/api/v1/analytics/top-hosts`	Top attacked hosts
`GET`	`/api/v1/analytics/timeline`	Traffic timeline with allowed/blocked/detected buckets
`GET`	`/api/v1/analytics/top-rules`	Most frequently triggered WAF rules
`GET`	`/api/v1/analytics/geo`	Geographic traffic distribution by country
`GET`	`/api/v1/events`	Server-Sent Events stream for live traffic

Dashboard & System

Method	Path	Description
`GET`	`/api/v1/dashboard`	Aggregate dashboard stats (host count, request count, block rate, top rule)
`GET`	`/api/v1/audit`	Admin audit log
`POST`	`/api/v1/reload`	Hot reload proxy hosts and WAF rules from the database

SMTP & Notifications

Method	Path	Description
`GET`	`/api/v1/smtp`	List SMTP sending profiles
`POST`	`/api/v1/smtp`	Create an SMTP profile
`PUT`	`/api/v1/smtp/{id}`	Update an SMTP profile
`DELETE`	`/api/v1/smtp/{id}`	Delete an SMTP profile
`POST`	`/api/v1/smtp/test`	Test SMTP connection

Mnemos Correlation

Method	Path	Description
`GET`	`/api/v1/correlation-events`	Query correlation events (filterable by host, source IP, rule, time range)

DDoS Protection

Method	Path	Description
`GET`	`/api/v1/ddos/status`	XDP attachment status, kernel version, mode
`GET`	`/api/v1/ddos/interfaces`	List available network interfaces
`GET`	`/api/v1/ddos/config`	Get global DDoS configuration
`PUT`	`/api/v1/ddos/config`	Update config (restarts XDP if interface changes)
`GET`	`/api/v1/ddos/rules`	List all DDoS rules
`POST`	`/api/v1/ddos/rules`	Create a new DDoS rule
`GET`	`/api/v1/ddos/rules/{id}`	Get a specific DDoS rule
`PUT`	`/api/v1/ddos/rules/{id}`	Update a DDoS rule
`DELETE`	`/api/v1/ddos/rules/{id}`	Delete a DDoS rule
`GET`	`/api/v1/ddos/bans`	List active bans (with live drop counts from kernel)
`POST`	`/api/v1/ddos/bans`	Manually ban an IP
`DELETE`	`/api/v1/ddos/bans/{ip}`	Unban an IP
`GET`	`/api/v1/ddos/events`	Query event log (filterable by type, source IP, time)
`GET`	`/api/v1/ddos/stats`	Real-time stats from kernel BPF maps

Protocol Streams

Method	Path	Description
`GET`	`/api/v1/streams`	List all stream hosts with runtime status
`POST`	`/api/v1/streams`	Create a new stream host
`GET`	`/api/v1/streams/{id}`	Get a stream host by ID
`PUT`	`/api/v1/streams/{id}`	Update a stream host
`DELETE`	`/api/v1/streams/{id}`	Delete a stream host
`GET`	`/api/v1/streams/stats`	Get runtime stats for all streams
`POST`	`/api/v1/streams/validate-port`	Validate a port before binding

Users

Method	Path	Description
`GET`	`/api/v1/users/me`	Get the currently authenticated user