API Reference

API Reference

The Nginx Proxy Manager exposes a REST API on port 81 by default.

Full OpenAPI 3.1 specification: docs/swagger.yaml

---

Viewing with Swagger UI

Option 1 — Docker (recommended)

cd /opt/npm

docker run --rm -p 8080:8080 \
  -e SWAGGER_JSON=/spec/swagger.yaml \
  -v $(pwd)/docs:/spec \
  swaggerapi/swagger-ui

Open http://localhost:8080 — interactive API explorer with "Try it out" button.

Option 2 — Online editor

1. Open https://editor.swagger.io
2. File → Import File → select docs/swagger.yaml
3. Browse endpoints in the right panel

---

Authentication

All endpoints (except /, /schema, /version/check) require a Bearer token.

# 1. Get token
TOKEN=$(curl -s -X POST http://localhost:81/api/tokens \
  -H 'Content-Type: application/json' \
  -d '{"identity":"admin@example.com","secret":"changeme"}' \
  | python -c "import sys,json; print(json.load(sys.stdin)['token'])")

# 2. Use token
curl -s http://localhost:81/api/nginx/proxy-hosts \
  -H "Authorization: Bearer $TOKEN" | python -m json.tool

Default credentials (first run): admin@example.com / changeme

---

Module Coverage

API Endpoint	Method	Module Action	Supported
POST /tokens	POST	(role task)	✅
GET /nginx/proxy-hosts	GET	search-host	✅
POST /nginx/proxy-hosts	POST	create-host	✅
DELETE /nginx/proxy-hosts/{id}	DELETE	delete-host	✅
GET /nginx/proxy-hosts/{id}	GET	—	❌
PUT /nginx/proxy-hosts/{id}	PUT	—	❌
POST /nginx/proxy-hosts/{id}/enable	POST	—	❌
POST /nginx/proxy-hosts/{id}/disable	POST	—	❌
GET /nginx/certificates	GET	search-ssl	✅
POST /nginx/certificates	POST	create-ssl	✅
DELETE /nginx/certificates/{id}	DELETE	delete-ssl	✅
POST /nginx/certificates/{id}/renew	POST	—	❌
GET /nginx/certificates/{id}/download	GET	—	❌
POST /nginx/certificates/{id}/upload	POST	—	❌
GET /nginx/certificates/dns-providers	GET	—	❌
* /nginx/access-lists	*	—	❌
* /nginx/redirection-hosts	*	—	❌
* /nginx/dead-hosts	*	—	❌
* /nginx/streams	*	—	❌
* /users	*	—	❌
* /settings	*	—	❌
GET /reports/hosts	GET	—	❌

---

Key Endpoints

Proxy Hosts

Operation	Method	Path	Required fields
List all	GET	/nginx/proxy-hosts	—
Create	POST	/nginx/proxy-hosts	domain_names, forward_scheme, forward_host, forward_port
Get one	GET	/nginx/proxy-hosts/{id}	—
Update	PUT	/nginx/proxy-hosts/{id}	At least 1 field
Delete	DELETE	/nginx/proxy-hosts/{id}	—
Enable	POST	/nginx/proxy-hosts/{id}/enable	—
Disable	POST	/nginx/proxy-hosts/{id}/disable	—

Create Proxy Host — full body:

{
  "domain_names": ["app.example.com"],
  "forward_scheme": "http",
  "forward_host": "10.0.0.5",
  "forward_port": 8080,
  "certificate_id": "new",
  "ssl_forced": true,
  "hsts_enabled": false,
  "hsts_subdomains": false,
  "http2_support": false,
  "block_exploits": false,
  "caching_enabled": false,
  "allow_websocket_upgrade": true,
  "access_list_id": 0,
  "advanced_config": "",
  "enabled": true,
  "meta": {
    "letsencrypt_email": "admin@example.com",
    "letsencrypt_agree": true,
    "dns_challenge": false
  },
  "locations": [],
  "trust_forwarded_proto": false
}

Certificates

Operation	Method	Path	Required fields
List all	GET	/nginx/certificates	—
Create	POST	/nginx/certificates	provider
Get one	GET	/nginx/certificates/{id}	—
Delete	DELETE	/nginx/certificates/{id}	—
Renew	POST	/nginx/certificates/{id}/renew	—
Download	GET	/nginx/certificates/{id}/download	—
DNS Providers	GET	/nginx/certificates/dns-providers	—

Create Let's Encrypt certificate:

{
  "provider": "letsencrypt",
  "domain_names": ["test.example.com"],
  "meta": {
    "dns_challenge": false
  }
}

Create with DNS-01 challenge (wildcard):

{
  "provider": "letsencrypt",
  "domain_names": ["*.example.com"],
  "meta": {
    "dns_challenge": true,
    "dns_provider": "cloudflare",
    "dns_provider_credentials": "dns_cloudflare_api_token = YOUR_TOKEN",
    "propagation_seconds": 30
  }
}

Sub-locations

Proxy hosts support sub-location routing. Each location has its own forward_host and forward_port:

{
  "domain_names": ["app.example.com"],
  "forward_scheme": "http",
  "forward_host": "10.0.0.1",
  "forward_port": 80,
  "locations": [
    {
      "path": "/api",
      "forward_scheme": "http",
      "forward_host": "10.0.0.2",
      "forward_port": 3000
    },
    {
      "path": "/static",
      "forward_scheme": "http",
      "forward_host": "10.0.0.3",
      "forward_port": 8080
    }
  ]
}

---

Source

API spec reconstructed from the official NPM swagger.json (OpenAPI 3.1, all $ref resolved).