> ## Documentation Index > Fetch the complete documentation index at: https://wiki.krkn.tech/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Aegis REST API reference # 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 |