13 API Usage Guide

API Usage Guide

This page mirrors the practical API usage examples exposed through the DomNex documentation experience and the current control-plane API.

Authentication

All mutating endpoints require authentication. There is no unauthenticated write API.

# Session (WebUI)
GET  /api/v1/csrf
POST /api/v1/login

# Token (Automation)
Authorization: Bearer dnx_xxx

Token Permission Model

global:read / global:write
domains:read / domains:write
hosts:read / hosts:write
settings:read / settings:write
users:read / users:write
tokens:read / tokens:write
audit:read
reload:write
dns:write / cert:write

If no global scope is set:
domainIds limit access to these domains/hosts.

API Base

BASE=http://<domnex>:8443
TOKEN=dnx_xxx

curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/me"

Golden Path (One Practical Sequence)

If you only follow one sequence, use this:

# 1) Preflight + create domain
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"example.com","dnsMode":"cloudflare","provider":"cloudflare","zoneId":""}' \
  "$BASE/api/v1/domains/preflight"

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"example.com","dnsMode":"cloudflare","certMode":"letsencrypt","provider":"cloudflare","zoneId":""}' \
  "$BASE/api/v1/domains"

# 2) Preflight + create subdomain
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"domain":"example.com","subdomain":"app","upstream":"http://192.168.1.50:3000","insecureTls":false,"haEnabled":false}' \
  "$BASE/api/v1/hosts/preflight"

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"domain":"example.com","subdomain":"app","upstream":"http://192.168.1.50:3000","insecureTls":false,"haEnabled":false}' \
  "$BASE/api/v1/hosts"

# 3) Verify domain/edge status
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/domains"
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/hosts"
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/domains/<domainId>/live-check"

# 4) Correlate via audit and investigations
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/audit?limit=200"

Tip: capture a trace ID from edge error pages and pivot it in Strategic Intel -> Investigations for direct correlation.

Domain Actions

# List domains
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/domains"

# Domain preflight
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"example.com","dnsMode":"cloudflare","provider":"cloudflare","zoneId":""}' \
  "$BASE/api/v1/domains/preflight"

# Create/Update domain
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"example.com","dnsMode":"cloudflare","certMode":"letsencrypt","provider":"cloudflare","zoneId":""}' \
  "$BASE/api/v1/domains"

# Domain live check
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/domains/24/live-check"

# Delete domain
curl -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/domains/24"

Subdomain / Host Actions

# List hosts
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/hosts"

# Host preflight
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"domain":"example.com","subdomain":"app","upstream":"https://127.0.0.1:3000","insecureTls":true,"haEnabled":false}' \
  "$BASE/api/v1/hosts/preflight"

# Create host
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"domain":"example.com","subdomain":"app","upstream":"https://127.0.0.1:3000","insecureTls":true,"haEnabled":false}' \
  "$BASE/api/v1/hosts"

# Create HA host
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "domain":"example.com",
    "subdomain":"app-ha",
    "insecureTls":true,
    "haEnabled":true,
    "haMode":"failover",
    "haBackends":[
      {"name":"server1","url":"https://10.0.0.11:8443"},
      {"name":"server2","url":"https://10.0.0.12:8443"}
    ]
  }' "$BASE/api/v1/hosts"

# Update host routing
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"upstream":"https://127.0.0.1:3001","insecureTls":false,"haEnabled":false}' \
  "$BASE/api/v1/hosts/5"

# Host diagnostics
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/hosts/diagnostics"

# Host retry
curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/hosts/5/retry"

# Update host auth page settings
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"enabled":true,"username":"musicuser","password":"StrongPass123"}' \
  "$BASE/api/v1/hosts/5/auth"

# Update host GeoIP policy
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"allow","countries":["DE","AT","CH"]}' \
  "$BASE/api/v1/hosts/5/geo"

# Set host disabled/enabled
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"disabled":true}' \
  "$BASE/api/v1/hosts/5/disable"

# Set host maintenance on/off
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"enabled":true}' \
  "$BASE/api/v1/hosts/5/maintenance"

# Delete host
curl -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/hosts/5"

Traffic & Statistics

# 24h overview across hosts
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/traffic/overview?hours=24"

# 24h traffic details for one host
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/traffic/hosts/5?hours=24"

Threat Intel

# Read threat intel config
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/threat-intel/config"

# Update threat intel config (2-mode model)
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"enabled":true,"mode":"auto_mode","syncHours":24}' \
  "$BASE/api/v1/threat-intel/config"

# List feeds
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/threat-intel/feeds"

# Add/update feed
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"blocklist.de all","url":"https://lists.blocklist.de/lists/all.txt","enabled":true}' \
  "$BASE/api/v1/threat-intel/feeds"

# Manual sync
curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/threat-intel/sync"

# Threat Intel views
# UI naming:
# - New     -> /matches
# - Watched -> /offenders   (legacy endpoint name kept for compatibility)
# - Blocked -> /blocked
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/threat-intel/matches?hours=24&decision=all&q=&page=1&pageSize=100"
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/threat-intel/offenders?hours=24&page=1&pageSize=100"
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/threat-intel/matches/198.51.100.10/targets?hours=24&limit=100"
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/threat-intel/blocked?hours=24&q=&page=1&pageSize=100"

# Allowlist overrides
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/threat-intel/allowlist"
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"ip":"198.51.100.10","reason":"trusted scanner"}' \
  "$BASE/api/v1/threat-intel/actions/allow"
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"ip":"198.51.100.10"}' \
  "$BASE/api/v1/threat-intel/actions/unallow"

System Actions

# Read settings
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/settings"

# Update settings
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"acmeEmail":"admin@example.com","acmeStaging":false,"publicIpv4":"203.0.113.10"}' \
  "$BASE/api/v1/settings"

# Service reload
curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/reload"

# Audit logs
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/audit"

Backup API

# Read backup schedule/FTP settings
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/backup/settings"

# Update backup schedule/FTP settings
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "intervalHours": 24,
    "passphrase": "VeryStrongPassphrase123",
    "ftp": {
      "enabled": true,
      "host": "ftp.example.net",
      "port": 21,
      "username": "backup-user",
      "remoteDir": "/domnex/backups",
      "tlsMode": "explicit"
    },
    "ftpPassword": "FtpStrongPassword123"
  }' \
  "$BASE/api/v1/backup/settings"

# Trigger post-restore check manually
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{}' "$BASE/api/v1/backup/post-restore-check"

User & Token Management

# User list
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/users"

# Create user
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"username":"ops1","password":"SuperSecret123","role":"domain-admin","domainIds":[24]}' \
  "$BASE/api/v1/users"

# Token list
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/tokens"

# Create token (domain scoped)
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name":"ci-token",
    "role":"operator",
    "domainIds":[24],
    "permissions":{"domainRead":true,"domainWrite":true,"globalRead":false,"globalWrite":false,"systemRead":false,"systemWrite":false},
    "scopes":[],
    "expiresIn":"720h"
  }' "$BASE/api/v1/tokens"

# Token revoke
curl -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/tokens/2"