API Reference

Use the Nginx Proxy Guard API to control the system programmatically.

Authentication

All API endpoints (except /api/v1/auth/login and /api/v1/challenge/*) require authentication via the following header.

# JWT Bearer token
Authorization: Bearer <jwt_token>

# API token
Authorization: Bearer ng_<api_token>

Authentication

Public Endpoints (No Authentication Required)

Method	Endpoint	Description
POST	`/api/v1/auth/login`	Log in
POST	`/api/v1/auth/logout`	Log out
GET	`/api/v1/auth/status`	Check authentication status
POST	`/api/v1/auth/verify-2fa`	Verify 2FA code

Authentication Management

Method	Endpoint	Description
GET	`/api/v1/auth/me`	Current user information
GET	`/api/v1/auth/account`	Account details
POST	`/api/v1/auth/change-credentials`	Change username/email
POST	`/api/v1/auth/change-password`	Change password
POST	`/api/v1/auth/2fa/setup`	Start 2FA setup
POST	`/api/v1/auth/2fa/enable`	Enable 2FA
POST	`/api/v1/auth/2fa/disable`	Disable 2FA
GET	`/api/v1/auth/language`	Get language setting
PUT	`/api/v1/auth/language`	Change language setting
GET	`/api/v1/auth/font`	Get font setting
PUT	`/api/v1/auth/font`	Change font setting

API Token Management

Method	Endpoint	Description
GET	`/api/v1/api-tokens`	List tokens
POST	`/api/v1/api-tokens`	Create a new token
GET	`/api/v1/api-tokens/permissions`	List available permissions
GET	`/api/v1/api-tokens/:id`	Token details
PUT	`/api/v1/api-tokens/:id`	Update token
POST	`/api/v1/api-tokens/:id/revoke`	Revoke token
DELETE	`/api/v1/api-tokens/:id`	Delete token
GET	`/api/v1/api-tokens/:id/usage`	Token usage statistics

Proxy Host Management

Method	Endpoint	Description
GET	`/api/v1/proxy-hosts`	List hosts
POST	`/api/v1/proxy-hosts`	Create a new host
GET	`/api/v1/proxy-hosts/by-domain/:domain`	Look up by domain
POST	`/api/v1/proxy-hosts/sync`	Sync all configurations
GET	`/api/v1/proxy-hosts/:id`	Get details
PUT	`/api/v1/proxy-hosts/:id`	Update host
DELETE	`/api/v1/proxy-hosts/:id`	Delete host
POST	`/api/v1/proxy-hosts/:id/test`	Connection test

SSL Certificate Management

Method	Endpoint	Description
GET	`/api/v1/certificates`	List certificates
POST	`/api/v1/certificates`	Issue Let's Encrypt certificate
POST	`/api/v1/certificates/upload`	Upload custom certificate
GET	`/api/v1/certificates/expiring`	List expiring certificates
GET	`/api/v1/certificates/:id`	Certificate details
DELETE	`/api/v1/certificates/:id`	Delete certificate
POST	`/api/v1/certificates/:id/renew`	Renew certificate

DNS Provider Management

Method	Endpoint	Description
GET	`/api/v1/dns-providers`	List providers
POST	`/api/v1/dns-providers`	Create provider
POST	`/api/v1/dns-providers/test`	Test credentials
GET	`/api/v1/dns-providers/default`	Get default provider
GET	`/api/v1/dns-providers/:id`	Provider details
PUT	`/api/v1/dns-providers/:id`	Update provider
DELETE	`/api/v1/dns-providers/:id`	Delete provider

DDNS Records

Method	Endpoint	Description
GET	`/api/v1/ddns-records`	List DDNS records
POST	`/api/v1/ddns-records`	Create DDNS record
POST	`/api/v1/ddns-records/sync`	Sync all records
POST	`/api/v1/ddns-records/import-from-hosts`	Bulk-enable DDNS from proxy hosts
GET	`/api/v1/ddns-records/:id`	Record details
PUT	`/api/v1/ddns-records/:id`	Update record
DELETE	`/api/v1/ddns-records/:id`	Delete record
POST	`/api/v1/ddns-records/:id/sync`	Sync a single record

Security Settings (Per Host)

Rate Limiting

Method	Endpoint	Description
GET	`/api/v1/proxy-hosts/:id/rate-limit`	Get rate limit
PUT	`/api/v1/proxy-hosts/:id/rate-limit`	Configure rate limit
DELETE	`/api/v1/proxy-hosts/:id/rate-limit`	Delete rate limit

Fail2ban

Method	Endpoint	Description
GET	`/api/v1/proxy-hosts/:id/fail2ban`	Get Fail2ban
PUT	`/api/v1/proxy-hosts/:id/fail2ban`	Configure Fail2ban
DELETE	`/api/v1/proxy-hosts/:id/fail2ban`	Delete Fail2ban

Bot Filter

Method	Endpoint	Description
GET	`/api/v1/proxy-hosts/:id/bot-filter`	Get bot filter
PUT	`/api/v1/proxy-hosts/:id/bot-filter`	Configure bot filter
DELETE	`/api/v1/proxy-hosts/:id/bot-filter`	Delete bot filter
GET	`/api/v1/bots/known`	List known bots

GeoIP Restrictions

Method	Endpoint	Description
GET	`/api/v1/proxy-hosts/:id/geo`	Get geo restrictions
POST	`/api/v1/proxy-hosts/:id/geo`	Create geo restrictions
PUT	`/api/v1/proxy-hosts/:id/geo`	Update geo restrictions
DELETE	`/api/v1/proxy-hosts/:id/geo`	Delete geo restrictions
GET	`/api/v1/geo/countries`	List country codes

URI Blocking

Method	Endpoint	Description
GET	`/api/v1/uri-blocks`	List all URI blocks
POST	`/api/v1/uri-blocks/bulk-add-rule`	Bulk add rules
GET	`/api/v1/proxy-hosts/:id/uri-block`	Get per-host URI block
PUT	`/api/v1/proxy-hosts/:id/uri-block`	Configure per-host URI block
DELETE	`/api/v1/proxy-hosts/:id/uri-block`	Delete per-host URI block
POST	`/api/v1/proxy-hosts/:id/uri-block/rules`	Add rule
DELETE	`/api/v1/proxy-hosts/:id/uri-block/rules/:ruleId`	Delete rule
GET	`/api/v1/global-uri-block`	Get global URI block
PUT	`/api/v1/global-uri-block`	Configure global URI block
POST	`/api/v1/global-uri-block/rules`	Add global rule
DELETE	`/api/v1/global-uri-block/rules/:ruleId`	Delete global rule

Security Headers

Method	Endpoint	Description
GET	`/api/v1/proxy-hosts/:id/security-headers`	Get security headers
PUT	`/api/v1/proxy-hosts/:id/security-headers`	Configure security headers
DELETE	`/api/v1/proxy-hosts/:id/security-headers`	Delete security headers
GET	`/api/v1/security-headers/presets`	List header presets
POST	`/api/v1/proxy-hosts/:id/security-headers/preset/:preset`	Apply preset

Challenge (CAPTCHA)

Method	Endpoint	Description
GET	`/api/v1/challenge-config`	Global challenge settings
PUT	`/api/v1/challenge-config`	Change global challenge settings
GET	`/api/v1/challenge-config/stats`	Challenge statistics
GET	`/api/v1/proxy-hosts/:id/challenge`	Per-host challenge settings
PUT	`/api/v1/proxy-hosts/:id/challenge`	Change per-host challenge settings
DELETE	`/api/v1/proxy-hosts/:id/challenge`	Delete per-host challenge

Cloud Provider Blocking

Method	Endpoint	Description
GET	`/api/v1/cloud-providers`	List cloud providers
GET	`/api/v1/cloud-providers/by-region`	Providers by region
GET	`/api/v1/cloud-providers/:slug`	Provider details
GET	`/api/v1/proxy-hosts/:id/blocked-cloud-providers`	Get blocked providers
PUT	`/api/v1/proxy-hosts/:id/blocked-cloud-providers`	Configure blocked providers

Upstream (Load Balancing)

Method	Endpoint	Description
GET	`/api/v1/proxy-hosts/:id/upstream`	Get upstream (load-balanced backend pool)
PUT	`/api/v1/proxy-hosts/:id/upstream`	Configure upstream
DELETE	`/api/v1/proxy-hosts/:id/upstream`	Delete upstream
GET	`/api/v1/upstreams/:id/health`	Upstream server health

WAF Management

WAF Testing

Method	Endpoint	Description
GET	`/api/v1/waf-test/patterns`	List test patterns
POST	`/api/v1/waf-test/test`	Test a single pattern
POST	`/api/v1/waf-test/test-all`	Test all patterns

WAF Rule Management

Method	Endpoint	Description
GET	`/api/v1/waf/rules`	All OWASP CRS rules
GET	`/api/v1/waf/hosts`	WAF settings for all hosts
GET	`/api/v1/waf/hosts/:id/config`	Per-host WAF settings
GET	`/api/v1/waf/hosts/:id/history`	Policy change history
POST	`/api/v1/waf/hosts/:id/rules/:ruleId/disable`	Disable host rule
POST	`/api/v1/waf/rules/disable-by-host`	Disable rule by domain
DELETE	`/api/v1/waf/hosts/:id/rules/:ruleId/disable`	Enable host rule
GET	`/api/v1/waf/global/rules`	Global rule status
GET	`/api/v1/waf/global/exclusions`	List global exclusions
GET	`/api/v1/waf/global/history`	Global policy history
POST	`/api/v1/waf/global/rules/:ruleId/disable`	Disable global rule
DELETE	`/api/v1/waf/global/rules/:ruleId/disable`	Enable global rule

IP Block Management

Method	Endpoint	Description
GET	`/api/v1/banned-ips`	List banned IPs
POST	`/api/v1/banned-ips`	Manually ban an IP
DELETE	`/api/v1/banned-ips/:id`	Unban IP by ID
DELETE	`/api/v1/banned-ips`	Unban by IP address
GET	`/api/v1/banned-ips/history`	Get ban history
GET	`/api/v1/banned-ips/history/stats`	Ban statistics
GET	`/api/v1/banned-ips/history/ip/:ip`	History for a specific IP

Filter Subscriptions

Method	Endpoint	Description
GET	`/api/v1/filter-subscriptions`	List subscriptions
POST	`/api/v1/filter-subscriptions`	Create subscription
GET	`/api/v1/filter-subscriptions/catalog`	Preset blocklist catalog
POST	`/api/v1/filter-subscriptions/catalog/subscribe`	Subscribe to a catalog list
GET	`/api/v1/filter-subscriptions/:id`	Subscription details
PUT	`/api/v1/filter-subscriptions/:id`	Update subscription
DELETE	`/api/v1/filter-subscriptions/:id`	Delete subscription
POST	`/api/v1/filter-subscriptions/:id/refresh`	Refresh entries now
GET	`/api/v1/filter-subscriptions/:id/exclusions`	List per-host exclusions
POST	`/api/v1/filter-subscriptions/:id/exclusions/:hostId`	Add per-host exclusion
DELETE	`/api/v1/filter-subscriptions/:id/exclusions/:hostId`	Remove per-host exclusion
GET	`/api/v1/filter-subscriptions/:id/entry-exclusions`	List entry exclusions
POST	`/api/v1/filter-subscriptions/:id/entry-exclusions`	Add entry exclusion
DELETE	`/api/v1/filter-subscriptions/:id/entry-exclusions`	Remove entry exclusion

Redirect Hosts

Method	Endpoint	Description
GET	`/api/v1/redirect-hosts`	List redirects
POST	`/api/v1/redirect-hosts`	Create redirect
GET	`/api/v1/redirect-hosts/:id`	Redirect details
PUT	`/api/v1/redirect-hosts/:id`	Update redirect
DELETE	`/api/v1/redirect-hosts/:id`	Delete redirect

Access Lists (ACL)

Method	Endpoint	Description
GET	`/api/v1/access-lists`	List access lists
POST	`/api/v1/access-lists`	Create access list
GET	`/api/v1/access-lists/:id`	Access list details
PUT	`/api/v1/access-lists/:id`	Update access list
DELETE	`/api/v1/access-lists/:id`	Delete access list

Logs & Monitoring

Dashboard

Method	Endpoint	Description
GET	`/api/v1/dashboard`	Dashboard summary data
GET	`/api/v1/dashboard/health`	System health status
GET	`/api/v1/dashboard/health/history`	Health status history
GET	`/api/v1/dashboard/stats/hourly`	Hourly statistics
GET	`/api/v1/dashboard/containers`	Docker container status
GET	`/api/v1/dashboard/geoip-stats`	GeoIP statistics data

Unified Logs

Method	Endpoint	Description
GET	`/api/v1/logs`	Query logs (with filtering)
POST	`/api/v1/logs`	Add log
GET	`/api/v1/logs/stats`	Log statistics
GET	`/api/v1/logs/settings`	Get log settings
PUT	`/api/v1/logs/settings`	Change log settings
POST	`/api/v1/logs/cleanup`	Clean up old logs
GET	`/api/v1/logs/autocomplete/hosts`	Host autocomplete
GET	`/api/v1/logs/autocomplete/ips`	IP autocomplete
GET	`/api/v1/logs/autocomplete/user-agents`	User-Agent autocomplete
GET	`/api/v1/logs/autocomplete/countries`	Country autocomplete
GET	`/api/v1/logs/autocomplete/uris`	URI autocomplete
GET	`/api/v1/logs/autocomplete/methods`	HTTP method autocomplete

Audit Logs

Method	Endpoint	Description
GET	`/api/v1/audit-logs`	Query audit logs
GET	`/api/v1/audit-logs/actions`	List action types
GET	`/api/v1/audit-logs/resource-types`	List resource types
GET	`/api/v1/audit-logs/api-tokens`	API token usage history

System Logs

Method	Endpoint	Description
GET	`/api/v1/system-logs`	Query system logs
GET	`/api/v1/system-logs/stats`	System log statistics
POST	`/api/v1/system-logs/cleanup`	Clean up system logs
GET	`/api/v1/system-logs/sources`	List log sources
GET	`/api/v1/system-logs/levels`	List log levels

Settings Management

Global Nginx Settings

Method	Endpoint	Description
GET	`/api/v1/settings`	Get global settings
PUT	`/api/v1/settings`	Change global settings
POST	`/api/v1/settings/reset`	Reset to defaults
GET	`/api/v1/settings/presets`	List settings presets
POST	`/api/v1/settings/preset/:preset`	Apply preset

System Settings

Method	Endpoint	Description
GET	`/api/v1/system-settings`	Get system settings
PUT	`/api/v1/system-settings`	Change system settings
GET	`/api/v1/system-settings/geoip/status`	Check GeoIP status
POST	`/api/v1/system-settings/geoip/update`	Update GeoIP database
GET	`/api/v1/system-settings/geoip/history`	GeoIP update history
POST	`/api/v1/system-settings/acme/test`	Test ACME configuration
GET	`/api/v1/system-settings/log-files`	List log files
GET	`/api/v1/system-settings/log-files/:filename/download`	Download log file
GET	`/api/v1/system-settings/log-files/:filename/view`	View log file
DELETE	`/api/v1/system-settings/log-files/:filename`	Delete log file
POST	`/api/v1/system-settings/log-files/rotate`	Rotate logs
GET	`/api/v1/system-settings/logs`	Log retention settings
PUT	`/api/v1/system-settings/logs`	Change log retention settings

Backup & Restore

Method	Endpoint	Description
GET	`/api/v1/backups`	List backups
POST	`/api/v1/backups`	Create backup
POST	`/api/v1/backups/upload-restore`	Upload and restore backup
GET	`/api/v1/backups/stats`	Backup statistics
GET	`/api/v1/backups/:id`	Backup information
GET	`/api/v1/backups/:id/download`	Download backup
DELETE	`/api/v1/backups/:id`	Delete backup
POST	`/api/v1/backups/:id/restore`	Restore backup

Testing & Validation

Method	Endpoint	Description
POST	`/api/v1/test/nginx-config`	Nginx config syntax check
POST	`/api/v1/test/proxy-host/:id`	Proxy connection test
GET	`/api/v1/test/system/self-check`	System self-diagnosis
GET	`/api/v1/test/backup-restore`	Backup/restore test

System Status

Method	Endpoint	Description
GET	`/api/v1/status`	API status
GET	`/api/v1/health`	Health check
GET	`/api/docs`	Swagger UI
GET	`/api/docs/swagger.yaml`	Swagger spec