pfSense API

pfSense REST API provided by the pfrest package.

Overview

Base URL

https://pfsense-01.inside.domusdigitalis.dev:443/api/v2/

Auth

API key or JWT

Format

JSON

Package

pfrest (install via Package Manager)

Key Endpoints

Resource Path netapi Command

DNS Host Overrides

/services/unbound/host_overrides

netapi pfsense dns list

Firewall Aliases

/firewall/alias

netapi pfsense aliases

Firewall Rules

/firewall/rule

-

System Info

/system/info

-

Interfaces

/interface

-

DHCP Leases

/services/dhcpd/lease

-

Examples

List DNS Overrides

# netapi
netapi pfsense dns list

# curl
curl -ks -H "Authorization: Bearer $PFSENSE_TOKEN" \
  "https://$PFSENSE_HOST/api/v2/services/unbound/host_overrides" | jq

Add DNS Override

# netapi
netapi pfsense dns add -h k3s-master-01 -d inside.domusdigitalis.dev -i 10.50.1.120 --descr "k3s control plane"

# curl
curl -ks -H "Authorization: Bearer $PFSENSE_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "https://$PFSENSE_HOST/api/v2/services/unbound/host_overrides" \
  -d '{
    "host": "k3s-master-01",
    "domain": "inside.domusdigitalis.dev",
    "ip": "10.50.1.120",
    "descr": "k3s control plane"
  }'

Delete DNS Override

# netapi (by ID)
netapi pfsense dns delete {id}

# curl
curl -ks -H "Authorization: Bearer $PFSENSE_TOKEN" \
  -X DELETE "https://$PFSENSE_HOST/api/v2/services/unbound/host_overrides/{id}"

List Firewall Aliases

# netapi
netapi pfsense aliases

# curl
curl -ks -H "Authorization: Bearer $PFSENSE_TOKEN" \
  "https://$PFSENSE_HOST/api/v2/firewall/alias" | jq '.data[].name'

Environment Setup

# Load from dsec
dsource d000 dev/network

# Or manually
export PFSENSE_HOST="pfsense-01.inside.domusdigitalis.dev"
export PFSENSE_TOKEN="<from pfSense API settings>"

Learnings

pfSense API Gotchas

  • pfrest package must be installed from Package Manager

  • API key generated in System > API

  • DNS changes require Unbound restart (handled automatically by API)

  • Some operations require ID (get from list operation first)

  • Rate limiting may apply for bulk operations