{ "openapi": "3.0.0", "info": { "title": "Nginx Proxy Manager API", "version": "2.x.x" }, "servers": [ { "url": "http://127.0.0.1:81/api" } ], "paths": { "/": { "get": { "operationId": "health", "summary": "Returns the API health status", "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "status": "OK", "version": { "major": 2, "minor": 1, "revision": 0 } } } }, "schema": { "$ref": "#/components/schemas/HealthObject" } } } } } } }, "/nginx/proxy-hosts": { "get": { "operationId": "getProxyHosts", "summary": "Get all proxy hosts", "tags": ["Proxy Hosts"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "query", "name": "expand", "description": "Expansions", "schema": { "type": "string", "enum": ["access_list", "owner", "certificate"] } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": [ { "id": 1, "created_on": "2023-03-30T01:12:23.000Z", "modified_on": "2023-03-30T02:15:40.000Z", "owner_user_id": 1, "domain_names": ["aasdasdad"], "forward_host": "asdasd", "forward_port": 80, "access_list_id": 0, "certificate_id": 0, "ssl_forced": 0, "caching_enabled": 0, "block_exploits": 0, "advanced_config": "sdfsdfsdf", "meta": { "letsencrypt_agree": false, "dns_challenge": false, "nginx_online": false, "nginx_err": "Command failed: /usr/sbin/nginx -t -g \"error_log off;\"\nnginx: [emerg] unknown directive \"sdfsdfsdf\" in /data/nginx/proxy_host/1.conf:37\nnginx: configuration file /etc/nginx/nginx.conf test failed\n" }, "allow_websocket_upgrade": 0, "http2_support": 0, "forward_scheme": "http", "enabled": 1, "locations": [], "hsts_enabled": 0, "hsts_subdomains": 0, "owner": { "id": 1, "created_on": "2023-03-30T01:11:50.000Z", "modified_on": "2023-03-30T01:11:50.000Z", "is_deleted": 0, "is_disabled": 0, "email": "admin@example.com", "name": "Administrator", "nickname": "Admin", "avatar": "", "roles": ["admin"] }, "access_list": null, "certificate": null }, { "id": 2, "created_on": "2023-03-30T02:11:49.000Z", "modified_on": "2023-03-30T02:11:49.000Z", "owner_user_id": 1, "domain_names": ["test.example.com"], "forward_host": "1.1.1.1", "forward_port": 80, "access_list_id": 0, "certificate_id": 0, "ssl_forced": 0, "caching_enabled": 0, "block_exploits": 0, "advanced_config": "", "meta": { "letsencrypt_agree": false, "dns_challenge": false, "nginx_online": true, "nginx_err": null }, "allow_websocket_upgrade": 0, "http2_support": 0, "forward_scheme": "http", "enabled": 1, "locations": [], "hsts_enabled": 0, "hsts_subdomains": 0, "owner": { "id": 1, "created_on": "2023-03-30T01:11:50.000Z", "modified_on": "2023-03-30T01:11:50.000Z", "is_deleted": 0, "is_disabled": 0, "email": "admin@example.com", "name": "Administrator", "nickname": "Admin", "avatar": "", "roles": ["admin"] }, "access_list": null, "certificate": null } ] } }, "schema": { "$ref": "#/components/schemas/ProxyHostsList" } } } } } }, "post": { "operationId": "createProxyHost", "summary": "Create a Proxy Host", "tags": ["Proxy Hosts"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "body", "name": "proxyhost", "description": "Proxy Host Payload", "required": true, "schema": { "$ref": "#/components/schemas/ProxyHostObject" } } ], "responses": { "201": { "description": "201 response", "content": { "application/json": { "examples": { "default": { "value": { "id": 3, "created_on": "2023-03-30T02:31:27.000Z", "modified_on": "2023-03-30T02:31:27.000Z", "owner_user_id": 1, "domain_names": ["test2.example.com"], "forward_host": "1.1.1.1", "forward_port": 80, "access_list_id": 0, "certificate_id": 0, "ssl_forced": 0, "caching_enabled": 0, "block_exploits": 0, "advanced_config": "", "meta": { "letsencrypt_agree": false, "dns_challenge": false }, "allow_websocket_upgrade": 0, "http2_support": 0, "forward_scheme": "http", "enabled": 1, "locations": [], "hsts_enabled": 0, "hsts_subdomains": 0, "certificate": null, "owner": { "id": 1, "created_on": "2023-03-30T01:11:50.000Z", "modified_on": "2023-03-30T01:11:50.000Z", "is_deleted": 0, "is_disabled": 0, "email": "admin@example.com", "name": "Administrator", "nickname": "Admin", "avatar": "", "roles": ["admin"] }, "access_list": null, "use_default_location": true, "ipv6": true } } }, "schema": { "$ref": "#/components/schemas/ProxyHostObject" } } } } } } }, "/schema": { "get": { "operationId": "schema", "responses": { "200": { "description": "200 response" } }, "summary": "Returns this swagger API schema" } }, "/tokens": { "get": { "operationId": "refreshToken", "summary": "Refresh your access token", "tags": ["Tokens"], "security": [ { "BearerAuth": ["tokens"] } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "expires": 1566540510, "token": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.ey...xaHKYr3Kk6MvkUjcC4" } } }, "schema": { "$ref": "#/components/schemas/TokenObject" } } } } } }, "post": { "operationId": "requestToken", "parameters": [ { "description": "Credentials Payload", "in": "body", "name": "credentials", "required": true, "schema": { "additionalProperties": false, "properties": { "identity": { "minLength": 1, "type": "string" }, "scope": { "minLength": 1, "type": "string", "enum": ["user"] }, "secret": { "minLength": 1, "type": "string" } }, "required": ["identity", "secret"], "type": "object" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "default": { "value": { "result": { "expires": 1566540510, "token": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.ey...xaHKYr3Kk6MvkUjcC4" } } } }, "schema": { "$ref": "#/components/schemas/TokenObject" } } }, "description": "200 response" } }, "summary": "Request a new access token from credentials", "tags": ["Tokens"] } }, "/settings": { "get": { "operationId": "getSettings", "summary": "Get all settings", "tags": ["Settings"], "security": [ { "BearerAuth": ["settings"] } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": [ { "id": "default-site", "name": "Default Site", "description": "What to show when Nginx is hit with an unknown Host", "value": "congratulations", "meta": {} } ] } }, "schema": { "$ref": "#/components/schemas/SettingsList" } } } } } } }, "/settings/{settingID}": { "get": { "operationId": "getSetting", "summary": "Get a setting", "tags": ["Settings"], "security": [ { "BearerAuth": ["settings"] } ], "parameters": [ { "in": "path", "name": "settingID", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Setting ID", "example": "default-site" } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "id": "default-site", "name": "Default Site", "description": "What to show when Nginx is hit with an unknown Host", "value": "congratulations", "meta": {} } } }, "schema": { "$ref": "#/components/schemas/SettingObject" } } } } } }, "put": { "operationId": "updateSetting", "summary": "Update a setting", "tags": ["Settings"], "security": [ { "BearerAuth": ["settings"] } ], "parameters": [ { "in": "path", "name": "settingID", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Setting ID", "example": "default-site" }, { "in": "body", "name": "setting", "description": "Setting Payload", "required": true, "schema": { "$ref": "#/components/schemas/SettingObject" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "id": "default-site", "name": "Default Site", "description": "What to show when Nginx is hit with an unknown Host", "value": "congratulations", "meta": {} } } }, "schema": { "$ref": "#/components/schemas/SettingObject" } } } } } } }, "/users": { "get": { "operationId": "getUsers", "summary": "Get all users", "tags": ["Users"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "query", "name": "expand", "description": "Expansions", "schema": { "type": "string", "enum": ["permissions"] } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": [ { "id": 1, "created_on": "2020-01-30T09:36:08.000Z", "modified_on": "2020-01-30T09:41:04.000Z", "is_disabled": 0, "email": "jc@jc21.com", "name": "Jamie Curnow", "nickname": "James", "avatar": "//www.gravatar.com/avatar/6193176330f8d38747f038c170ddb193?default=mm", "roles": ["admin"] } ] }, "withPermissions": { "value": [ { "id": 1, "created_on": "2020-01-30T09:36:08.000Z", "modified_on": "2020-01-30T09:41:04.000Z", "is_disabled": 0, "email": "jc@jc21.com", "name": "Jamie Curnow", "nickname": "James", "avatar": "//www.gravatar.com/avatar/6193176330f8d38747f038c170ddb193?default=mm", "roles": ["admin"], "permissions": { "visibility": "all", "proxy_hosts": "manage", "redirection_hosts": "manage", "dead_hosts": "manage", "streams": "manage", "access_lists": "manage", "certificates": "manage" } } ] } }, "schema": { "$ref": "#/components/schemas/UsersList" } } } } } }, "post": { "operationId": "createUser", "summary": "Create a User", "tags": ["Users"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "body", "name": "user", "description": "User Payload", "required": true, "schema": { "$ref": "#/components/schemas/UserObject" } } ], "responses": { "201": { "description": "201 response", "content": { "application/json": { "examples": { "default": { "value": { "id": 2, "created_on": "2020-01-30T09:36:08.000Z", "modified_on": "2020-01-30T09:41:04.000Z", "is_disabled": 0, "email": "jc@jc21.com", "name": "Jamie Curnow", "nickname": "James", "avatar": "//www.gravatar.com/avatar/6193176330f8d38747f038c170ddb193?default=mm", "roles": ["admin"], "permissions": { "visibility": "all", "proxy_hosts": "manage", "redirection_hosts": "manage", "dead_hosts": "manage", "streams": "manage", "access_lists": "manage", "certificates": "manage" } } } }, "schema": { "$ref": "#/components/schemas/UserObject" } } } } } } }, "/users/{userID}": { "get": { "operationId": "getUser", "summary": "Get a user", "tags": ["Users"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "path", "name": "userID", "schema": { "oneOf": [ { "type": "string", "pattern": "^me$" }, { "type": "integer", "minimum": 1 } ] }, "required": true, "description": "User ID or 'me' for yourself", "example": 1 } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "id": 1, "created_on": "2020-01-30T09:36:08.000Z", "modified_on": "2020-01-30T09:41:04.000Z", "is_disabled": 0, "email": "jc@jc21.com", "name": "Jamie Curnow", "nickname": "James", "avatar": "//www.gravatar.com/avatar/6193176330f8d38747f038c170ddb193?default=mm", "roles": ["admin"] } } }, "schema": { "$ref": "#/components/schemas/UserObject" } } } } } }, "put": { "operationId": "updateUser", "summary": "Update a User", "tags": ["Users"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "path", "name": "userID", "schema": { "oneOf": [ { "type": "string", "pattern": "^me$" }, { "type": "integer", "minimum": 1 } ] }, "required": true, "description": "User ID or 'me' for yourself", "example": 2 }, { "in": "body", "name": "user", "description": "User Payload", "required": true, "schema": { "$ref": "#/components/schemas/UserObject" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "id": 2, "created_on": "2020-01-30T09:36:08.000Z", "modified_on": "2020-01-30T09:41:04.000Z", "is_disabled": 0, "email": "jc@jc21.com", "name": "Jamie Curnow", "nickname": "James", "avatar": "//www.gravatar.com/avatar/6193176330f8d38747f038c170ddb193?default=mm", "roles": ["admin"] } } }, "schema": { "$ref": "#/components/schemas/UserObject" } } } } } }, "delete": { "operationId": "deleteUser", "summary": "Delete a User", "tags": ["Users"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "path", "name": "userID", "schema": { "type": "integer", "minimum": 1 }, "required": true, "description": "User ID", "example": 2 } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": true } }, "schema": { "type": "boolean" } } } } } } }, "/users/{userID}/auth": { "put": { "operationId": "updateUserAuth", "summary": "Update a User's Authentication", "tags": ["Users"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "path", "name": "userID", "schema": { "oneOf": [ { "type": "string", "pattern": "^me$" }, { "type": "integer", "minimum": 1 } ] }, "required": true, "description": "User ID or 'me' for yourself", "example": 2 }, { "in": "body", "name": "user", "description": "User Payload", "required": true, "schema": { "$ref": "#/components/schemas/AuthObject" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": true } }, "schema": { "type": "boolean" } } } } } } }, "/users/{userID}/permissions": { "put": { "operationId": "updateUserPermissions", "summary": "Update a User's Permissions", "tags": ["Users"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "path", "name": "userID", "schema": { "type": "integer", "minimum": 1 }, "required": true, "description": "User ID", "example": 2 }, { "in": "body", "name": "user", "description": "Permissions Payload", "required": true, "schema": { "$ref": "#/components/schemas/PermissionsObject" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": true } }, "schema": { "type": "boolean" } } } } } } }, "/users/{userID}/login": { "put": { "operationId": "loginAsUser", "summary": "Login as this user", "tags": ["Users"], "security": [ { "BearerAuth": ["users"] } ], "parameters": [ { "in": "path", "name": "userID", "schema": { "type": "integer", "minimum": 1 }, "required": true, "description": "User ID", "example": 2 } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "token": "eyJhbGciOiJSUzI1NiIsInR...16OjT8B3NLyXg", "expires": "2020-01-31T10:56:23.239Z", "user": { "id": 1, "created_on": "2020-01-30T10:43:44.000Z", "modified_on": "2020-01-30T10:43:44.000Z", "is_disabled": 0, "email": "jc@jc21.com", "name": "Jamie Curnow", "nickname": "James", "avatar": "//www.gravatar.com/avatar/3c8d73f45fd8763f827b964c76e6032a?default=mm", "roles": ["admin"] } } } }, "schema": { "type": "object", "description": "Login object", "required": ["expires", "token", "user"], "additionalProperties": false, "properties": { "expires": { "description": "Token Expiry Unix Time", "example": 1566540249, "minimum": 1, "type": "number" }, "token": { "description": "JWT Token", "example": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.ey...xaHKYr3Kk6MvkUjcC4", "type": "string" }, "user": { "$ref": "#/components/schemas/UserObject" } } } } } } } } }, "/reports/hosts": { "get": { "operationId": "reportsHosts", "summary": "Report on Host Statistics", "tags": ["Reports"], "security": [ { "BearerAuth": ["reports"] } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "proxy": 20, "redirection": 1, "stream": 0, "dead": 1 } } }, "schema": { "$ref": "#/components/schemas/HostReportObject" } } } } } } }, "/audit-log": { "get": { "operationId": "getAuditLog", "summary": "Get Audit Log", "tags": ["Audit Log"], "security": [ { "BearerAuth": ["audit-log"] } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "default": { "value": { "proxy": 20, "redirection": 1, "stream": 0, "dead": 1 } } }, "schema": { "$ref": "#/components/schemas/HostReportObject" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "HealthObject": { "type": "object", "description": "Health object", "additionalProperties": false, "required": ["status", "version"], "properties": { "status": { "type": "string", "description": "Healthy", "example": "OK" }, "version": { "type": "object", "description": "The version object", "example": { "major": 2, "minor": 0, "revision": 0 }, "additionalProperties": false, "required": ["major", "minor", "revision"], "properties": { "major": { "type": "integer", "minimum": 0 }, "minor": { "type": "integer", "minimum": 0 }, "revision": { "type": "integer", "minimum": 0 } } } } }, "TokenObject": { "type": "object", "description": "Token object", "required": ["expires", "token"], "additionalProperties": false, "properties": { "expires": { "description": "Token Expiry Unix Time", "example": 1566540249, "minimum": 1, "type": "number" }, "token": { "description": "JWT Token", "example": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.ey...xaHKYr3Kk6MvkUjcC4", "type": "string" } } }, "ProxyHostObject": { "type": "object", "description": "Proxy Host object", "required": [ "id", "created_on", "modified_on", "owner_user_id", "domain_names", "forward_host", "forward_port", "access_list_id", "certificate_id", "ssl_forced", "caching_enabled", "block_exploits", "advanced_config", "meta", "allow_websocket_upgrade", "http2_support", "forward_scheme", "enabled", "locations", "hsts_enabled", "hsts_subdomains", "certificate", "use_default_location", "ipv6" ], "additionalProperties": false, "properties": { "id": { "type": "integer", "description": "Proxy Host ID", "minimum": 1, "example": 1 }, "created_on": { "type": "string", "description": "Created Date", "example": "2020-01-30T09:36:08.000Z" }, "modified_on": { "type": "string", "description": "Modified Date", "example": "2020-01-30T09:41:04.000Z" }, "owner_user_id": { "type": "integer", "minimum": 1, "example": 1 }, "domain_names": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "forward_host": { "type": "string", "minLength": 1 }, "forward_port": { "type": "integer", "minimum": 1 }, "access_list_id": { "type": "integer" }, "certificate_id": { "type": "integer" }, "ssl_forced": { "type": "integer" }, "caching_enabled": { "type": "integer" }, "block_exploits": { "type": "integer" }, "advanced_config": { "type": "string" }, "meta": { "type": "object" }, "allow_websocket_upgrade": { "type": "integer" }, "http2_support": { "type": "integer" }, "forward_scheme": { "type": "string" }, "enabled": { "type": "integer" }, "locations": { "type": "array" }, "hsts_enabled": { "type": "integer" }, "hsts_subdomains": { "type": "integer" }, "certificate": { "type": "object", "nullable": true }, "owner": { "type": "object", "nullable": true }, "access_list": { "type": "object", "nullable": true }, "use_default_location": { "type": "boolean" }, "ipv6": { "type": "boolean" } } }, "ProxyHostsList": { "type": "array", "description": "Proxyn Hosts list", "items": { "$ref": "#/components/schemas/ProxyHostObject" } }, "SettingObject": { "type": "object", "description": "Setting object", "required": ["id", "name", "description", "value", "meta"], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Setting ID", "minLength": 1, "example": "default-site" }, "name": { "type": "string", "description": "Setting Display Name", "minLength": 1, "example": "Default Site" }, "description": { "type": "string", "description": "Meaningful description", "minLength": 1, "example": "What to show when Nginx is hit with an unknown Host" }, "value": { "description": "Value in almost any form", "example": "congratulations", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "integer" }, { "type": "object" }, { "type": "number" }, { "type": "array" } ] }, "meta": { "description": "Extra metadata", "example": {}, "type": "object" } } }, "SettingsList": { "type": "array", "description": "Setting list", "items": { "$ref": "#/components/schemas/SettingObject" } }, "UserObject": { "type": "object", "description": "User object", "required": ["id", "created_on", "modified_on", "is_disabled", "email", "name", "nickname", "avatar", "roles"], "additionalProperties": false, "properties": { "id": { "type": "integer", "description": "User ID", "minimum": 1, "example": 1 }, "created_on": { "type": "string", "description": "Created Date", "example": "2020-01-30T09:36:08.000Z" }, "modified_on": { "type": "string", "description": "Modified Date", "example": "2020-01-30T09:41:04.000Z" }, "is_disabled": { "type": "integer", "minimum": 0, "maximum": 1, "description": "Is user Disabled (0 = false, 1 = true)", "example": 0 }, "email": { "type": "string", "description": "Email", "minLength": 3, "example": "jc@jc21.com" }, "name": { "type": "string", "description": "Name", "minLength": 1, "example": "Jamie Curnow" }, "nickname": { "type": "string", "description": "Nickname", "example": "James" }, "avatar": { "type": "string", "description": "Gravatar URL based on email, without scheme", "example": "//www.gravatar.com/avatar/6193176330f8d38747f038c170ddb193?default=mm" }, "roles": { "description": "Roles applied", "example": ["admin"], "type": "array", "items": { "type": "string" } } } }, "UsersList": { "type": "array", "description": "User list", "items": { "$ref": "#/components/schemas/UserObject" } }, "AuthObject": { "type": "object", "description": "Authentication Object", "required": ["type", "secret"], "properties": { "type": { "type": "string", "pattern": "^password$", "example": "password" }, "current": { "type": "string", "minLength": 1, "maxLength": 64, "example": "changeme" }, "secret": { "type": "string", "minLength": 8, "maxLength": 64, "example": "mySuperN3wP@ssword!" } } }, "PermissionsObject": { "type": "object", "properties": { "visibility": { "type": "string", "description": "Visibility Type", "enum": ["all", "user"] }, "access_lists": { "type": "string", "description": "Access Lists Permissions", "enum": ["hidden", "view", "manage"] }, "dead_hosts": { "type": "string", "description": "404 Hosts Permissions", "enum": ["hidden", "view", "manage"] }, "proxy_hosts": { "type": "string", "description": "Proxy Hosts Permissions", "enum": ["hidden", "view", "manage"] }, "redirection_hosts": { "type": "string", "description": "Redirection Permissions", "enum": ["hidden", "view", "manage"] }, "streams": { "type": "string", "description": "Streams Permissions", "enum": ["hidden", "view", "manage"] }, "certificates": { "type": "string", "description": "Certificates Permissions", "enum": ["hidden", "view", "manage"] } } }, "HostReportObject": { "type": "object", "properties": { "proxy": { "type": "integer", "description": "Proxy Hosts Count" }, "redirection": { "type": "integer", "description": "Redirection Hosts Count" }, "stream": { "type": "integer", "description": "Streams Count" }, "dead": { "type": "integer", "description": "404 Hosts Count" } } } } } }