Portmaster Developer API
This page lists all API endpoints of the Portmaster.
This page is very much in progress and may not be fully accurate and up to date. Additionally, the API itself is not stable yet. If you plan to develop something that interacts with the Portmaster, we'd love to hear from you and talk about it!
Some endpoints require authentication, which is handled with API Keys
. You can use an API key in a Basic
or Bearer
HTTP Authorization
Header.
For development, you may also enable the Development Mode , which disables authentication and gives you full access. Cross-origin requests are not allowed.
Badge | Meaning |
---|---|
User | Endpoint requires User privileges. |
Admin | Endpoint requires Admin privileges. |
Internal | Endpoint can only be used by the Portmaster itself. |
When hovering over a setting name - copy its name and URL formatted in markdown. This requires JavaScript. |
Database Websocket API
Admin
[WEBSOCKET] /api/database/v1
The websocket interface is not yet documented in a processable format. Please refer to the Portmaster Console App for more information and testing:
http://127.0.0.1:817/ui/modules/console/ (Requires Development Mode
)
Request HTTP Basic Auth
GET /api/v1/auth/basic
returns text/plain
data
Returns an HTTP Basic Auth request, if not authenticated.
Request HTTP Bearer Auth
GET /api/v1/auth/bearer
returns text/plain
data
Returns an HTTP Bearer Auth request, if not authenticated.
View Current Permissions
GET /api/v1/auth/permissions
returns application/json
data
Returns the current permissions assigned to the request.
Reset Authenticated Session
GET /api/v1/auth/reset
returns text/plain
data
Resets authentication status internally and in the browser.
Run Integration Self-Check
User
GET /api/v1/compat/self-check
returns text/plain
data
Runs a couple integration self-checks in order to see if the system integration works.
Export Configuration Options
GET /api/v1/config/options
returns application/json
data
Returns a list of all registered configuration options and their metadata. This does not include the current active or default settings.
Restart Portmaster
Admin
POST /api/v1/core/restart
returns text/plain
data
Restart the Portmaster Core Service.
Shut Down Portmaster
Internal
POST /api/v1/core/shutdown
returns text/plain
data
Shut down the Portmaster Core Service and all UI components.
Get Debug Information
GET /api/v1/debug/core
returns text/plain
data
Returns network debugging information, similar to debug/info, but with system status data.
Parameters:
-
style
- Method: GET
- Value:
github
- Description: Specify the formatting style. The default is simple markdown formatting.
Get CPU Profile
GET /api/v1/debug/cpu
returns text/plain
data
Parameters:
-
duration
- Method: GET
- Value:
10s
- Description: Specify the formatting style. The default is simple markdown formatting.
Get Debug Information
GET /api/v1/debug/info
returns text/plain
data
Returns debugging information, including the version and platform info, errors, logs and the current goroutine stack.
Parameters:
-
style
- Method: GET
- Value:
github
- Description: Specify the formatting style. The default is simple markdown formatting.
Get Network Debug Information
User
GET /api/v1/debug/network
returns text/plain
data
Returns network debugging information, similar to debug/core, but with connection data.
Parameters:
-
style
- Method: GET
- Value:
github
- Description: Specify the formatting style. The default is simple markdown formatting.
-
profile
- Method: GET
- Value:
<Source>/<ID>
- Description: Specify a profile source and ID for which network connection should be reported.
-
where
- Method: GET
- Value:
<query>
- Description: Specify a query to limit the connections included in the report. The default is to include all connections.
Get Network State Table Data
User
GET /api/v1/debug/network/state
returns application/json
data
Returns the current network state tables from the OS.
Get Goroutine Stack
GET /api/v1/debug/stack
returns text/plain
data
Returns the current goroutine stack.
Print Goroutine Stack
GET /api/v1/debug/stack/print
returns text/plain
data
Prints the current goroutine stack to stdout.
Get DNS Record from Cache
User
GET /api/v1/dns/cache/{query:[a-z0-9\.-]{0,512}\.[A-Z]{1,32}}
returns application/json
data
Returns cached dns records from the internal cache.
Parameters:
-
query (in path)
- Method: GET
- Value:
fqdn and query type
- Description: Specify the query like this: `example.com.A`.
Clear cached DNS records
User
POST /api/v1/dns/clear
returns text/plain
data
Deletes all saved DNS records from the database.
List DNS Resolvers
GET /api/v1/dns/resolvers
returns application/json
data
List currently configured DNS resolvers and their status.
Export API Endpoints
GET /api/v1/endpoints
returns application/json
data
Returns a list of all registered endpoints and their metadata.
Trigger Event
Internal
POST /api/v1/modules/{moduleName:.+}/trigger/{eventName:.+}
returns text/plain
data
Triggers an event of an internal module.
Get Default Gateways
User
GET /api/v1/network/gateways
returns application/json
data
Returns the current active default gateways of the network.
Get Approximate Internet Location
User
GET /api/v1/network/location
returns application/json
data
Returns an approximation of where the device is on the Internet.
Get Approximate Internet Location via Traceroute
User
GET /api/v1/network/location/traceroute
returns application/json
data
Returns an approximation of where the device is on the Internet using a the traceroute technique.
Get System Nameservers
User
GET /api/v1/network/nameservers
returns application/json
data
Returns the currently configured nameservers on the OS.
SPN Logout
Admin
DELETE /api/v1/spn/account/logout
returns text/plain
data
Logout from your SPN account.
Parameters:
-
purge
- Method: DELETE
- Value:
- Description: If set, account data is purged. Otherwise, the username and device ID are kept in order to log into the same device when logging in with the same user again.
SPN User Profile
User
GET /api/v1/spn/account/user/profile
returns application/json
data
Get the user profile of the logged in SPN account.
Parameters:
-
refresh
- Method: GET
- Value:
- Description: If set, the user profile is freshly fetched from the account server.
Get SPN map graph
User
GET /api/v1/spn/map/{map:[A-Za-z0-9]{1,255}}/graph{format:\.[a-z]{2,4}}
returns text/plain
data
Returns a graph of the given SPN map.
Parameters:
-
map (in path)
- Method: GET
- Value:
name of map
- Description: Specify the map you want to get the map for. The main map is called `main`.
-
format (in path)
- Method: GET
- Value:
file type
- Description: Specify the format you want to get the map in. Available values: `dot`, `html`. Please note that the html format is only available in development mode.
Get SPN map measurements
User
GET /api/v1/spn/map/{map:[A-Za-z0-9]{1,255}}/measurements
returns application/json
data
Returns the measurements of the map.
Get SPN map measurements as a table
User
GET /api/v1/spn/map/{map:[A-Za-z0-9]{1,255}}/measurements/table
returns text/plain
data
Returns the measurements of the map as a table.
Get SPN map optimization
User
GET /api/v1/spn/map/{map:[A-Za-z0-9]{1,255}}/optimization
returns application/json
data
Returns the calculated optimization for the map.
Get SPN map optimization as a table
User
GET /api/v1/spn/map/{map:[A-Za-z0-9]{1,255}}/optimization/table
returns text/plain
data
Returns the calculated optimization for the map as a table.
Get SPN map pins
User
GET /api/v1/spn/map/{map:[A-Za-z0-9]{1,255}}/pins
returns application/json
data
Returns a list of pins on the map.