Connectivity and System

Use the two pfsense:read routes to confirm that the controller can reach the firewall and to read its basic system details.

Why Use These Routes?

Tests the whole path, from the token to the firewall, in one request, so monitoring can tell a firewall problem from a client problem.
Returns three validated fields instead of raw uname output, so clients get a stable shape.
Needs only the read-only pfsense:read scope.

Check Connectivity

GET /api/v1/connectivity, also at GET /, runs the connectivity check. It signs in to the target firewall over SSH, runs uname -mrs, and signs out.

bash

printf 'header = "Authorization: Bearer %s"\n' "$PFSENSE_ACTIONS_TOKEN" \
  | curl --config - --silent --show-error --fail-with-body \
      https://actions.example.net/api/v1/connectivity

json

{
  "connected": true
}

200 means the sign-in and the command both succeeded, and 502 means either one failed.
Each call opens an SSH session, so the Docker health check is the better fit for frequent liveness probes.
To get an alert when the firewall stops answering, a scheduled check can do the polling for you, as described in Notifications.

Read System Information

GET /api/v1/system, also at GET /system, returns the firewall's system information as JSON.

bash

printf 'header = "Authorization: Bearer %s"\n' "$PFSENSE_ACTIONS_TOKEN" \
  | curl --config - --silent --show-error --fail-with-body \
      https://actions.example.net/api/v1/system

json

{
  "architecture": "amd64",
  "operatingSystem": "FreeBSD",
  "release": "14.0-CURRENT"
}

The values come from uname -mrs, split on whitespace into the operating system, release, and architecture.
Output that doesn't split into exactly three fields returns 502 instead of a partial body.
The response leaves out the hostname, interfaces, configuration, and the raw command output.

Responses

Status	Error code	Meaning
`200`	—	The SSH sign-in and `uname -mrs` succeeded.
`401`	`authentication_required`	The token is missing, malformed, unknown, or expired.
`403`	`scope_required`	The token doesn't have `pfsense:read`.
`429`	`rate_limited`	The client reached a rate limit.
`500`	`internal_error`	The controller hit an unexpected error.
`502`	`pfsense_unavailable`	The SSH sign-in failed.
`502`	`command_failed`	`uname -mrs` failed, or the system information route got unexpected output.
`503`	`connection_not_configured`	No pfSense connection is saved yet, or its credential was removed.

The full list is in Status Codes and Limits. A 502 or 500 also sends Action failed to the notification destinations that chose it, as described in Notifications.