This site is migrating to wiki.safing.io, which is being maintained by Safing and the community alike.

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. 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 )

Get Account Features User

GET /api/v1/account/features
returns application/json data

Returns all account features.

Returns the image of the featuare User

GET /api/v1/account/features/{id:[A-Za-z0-9_-]+}/icon
returns image/svg+xml data

Request an authentication token with a given set of permissions. The user will be prompted to either authorize or deny the request. Used for external or third-party tool integrations.

GET /api/v1/app/auth
returns application/json data

Parameters:
  • app-name
    • Method: GET
    • Value:
    • Description: The name of the application requesting access
  • read
    • Method: GET
    • Value:
    • Description: The requested read permission
  • write
    • Method: GET
    • Value:
    • Description: The requested write permission
  • ttl
    • Method: GET
    • Value:
    • Description: The time-to-live for the new access token. Defaults to 24h
Get the ID of the calling profile User

GET /api/v1/app/profile
returns application/json data

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.

Get Broadcast Notifications Matching Data Admin

GET /api/v1/broadcasts/matching-data
returns application/json data

Returns the data used by the broadcast notifications to match the instance.

Resets the Broadcast Notification States Admin

POST /api/v1/broadcasts/reset-state
returns text/plain data

Delete the cache of Broadcast Notifications, making them appear again.

Simulate Broadcast Notifications Admin

POST /api/v1/broadcasts/simulate
returns text/plain data

Test broadcast notifications by sending a valid source file in the body.

Parameters:
  • state
    • Method: POST
    • Value: true
    • Description: Check against state when deciding to display a broadcast notification. Acknowledgements are always saved.
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.

Update custom filter list User

POST /api/v1/customlists/update
returns text/plain data

Reload the filter list from the configured file.

Get Allocs Profile

GET /api/v1/debug/allocs
returns text/plain data

Gather and return the memory allocation profile.

	You can easily view this data in your browser with this command (with Go installed):
	`go tool pprof -http :8888 http://127.0.0.1:817/api/v1/debug/allocs`
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

Gather and return the CPU profile. This data needs to gathered over a period of time, which is specified using the duration parameter.

You can easily view this data in your browser with this command (with Go installed): go tool pprof -http :8888 http://127.0.0.1:817/api/v1/debug/cpu

Parameters:
  • duration
    • Method: GET
    • Value: 10s
    • Description: Specify the formatting style. The default is simple markdown formatting.
Get Heap Profile

GET /api/v1/debug/heap
returns text/plain data

Gather and return the heap memory profile.

	You can easily view this data in your browser with this command (with Go installed):
	`go tool pprof -http :8888 http://127.0.0.1:817/api/v1/debug/heap`
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.

Get Country Information User

GET /api/v1/intel/geoip/countries
returns application/json data

Returns a map of country information centers indexed by ISO-A2 country code

Get Module Status User

GET /api/v1/modules/status
returns application/json data

Returns status information of all modules.

Trigger Event Internal

POST /api/v1/modules/{moduleName:.+}/trigger/{eventName:.+}
returns text/plain data

Triggers an event of an internal module.

Active Connections Chart User

POST /api/v1/netquery/charts/connection-active
returns application/json data

Query the in-memory sqlite connection database and return a chart of active connections.

Apply connection history retention threshold User

POST /api/v1/netquery/history/cleanup
returns text/plain data

Remove connections from profile history User

POST /api/v1/netquery/history/clear
returns application/json data

Remove all connections from the history database for one or more profiles

Query Connections User User

GET /api/v1/netquery/query
POST /api/v1/netquery/query
returns application/json data

Query the in-memory sqlite connection database.

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.

Ping

GET /api/v1/ping
returns text/plain data

Pong.

SPN Login Admin

POST /api/v1/spn/account/login
returns text/plain data

Log into your SPN account.

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.
Update map intelligence. Internal

POST /api/v1/spn/map/{map:[A-Za-z0-9]{1,255}}/intel/update
returns text/plain data

Updates the intel data of the map.

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.

Calculate Route through SPN User

GET /api/v1/spn/map/{map:[A-Za-z0-9]{1,255}}/route/to/{destination:[a-z0-9_\.:-]{1,255}}
returns text/plain data

Returns a textual representation of the routing process.

Parameters:
  • profile
    • Method: GET
    • Value: <id>|global
    • Description: Specify a profile ID to load more settings for simulation.
  • encrypted
    • Method: GET
    • Value: true
    • Description: Specify to signify that the simulated connection should be regarded as encrypted. Only valid with a profile.
Re-initialize SPN Admin

POST /api/v1/spn/reinit
returns text/plain data

Stops the SPN, resets all caches and starts it again. The SPN account and settings are not changed.

Reload UI Assets User

POST /api/v1/ui/reload
returns text/plain data

Removes all assets from the cache and reloads the current (possibly updated) version from disk when requested.

Check for Updates User

POST /api/v1/updates/check
returns text/plain data

Triggers checking for updates.