esh-pfi-infrastructure/docs/pfi/opnsense-api-reference.md

OPNsense API — vendored reference + field-shape notes

Source: https://docs.opnsense.org/development/api.html (fetched 2026-09-13) Why vendored: the upstream page documents the REST conventions but explicitly not parameter shapes — "the auto-generated API documentation captures endpoints and HTTP methods but not all parameter details." Those shapes are where the time goes, so the hard-won ones are recorded in § Field shapes below.

Authentication

HTTP Basic auth: key = username, secret = password.

curl -s -u "$KEY:$SECRET" "http://<gw>/api/<module>/<controller>/<command>"

Fleet creds are vaulted: fv-gateway/opnsense-api-key, fv-gateway/opnsense-api-secret (see secret get). Authorization is per-user Effective Privileges — a key only reaches endpoints its owner is authorized for.

Conventions

• Endpoint pattern: /api/<module>/<controller>/<command>/[<param>/...]
• GET retrieves; POST creates, updates, or executes an action.
• Request bodies and responses are application/json.

Search endpoints take a paging body and return a rows envelope:

{"current":1,"rowCount":7,"sort":{},"searchPhrase":""}

{"total":10,"rowCount":7,"current":1,
 "rows":[{"id":"configd","locked":1,"running":1,"description":"System Configuration Daemon","name":"configd"}]}

Service control

/api/<module>/service/{status,start,stop,restart,reconfigure} — reconfigure writes config and applies it, which is normally the one you want after a settings/set. Observed status values include disabled, stopped, running — note disabled ≠ stopped: a disabled service will not start until its model's enabled field is set to "1".

⚠ Endpoints are ACTIONS — never probe for existence by calling them

A 404 tells you an endpoint is absent; a 200 tells you it ran. There is no safe "does this exist?" POST against a live firewall.

2026-09-15: looking for the call that applies a user change, a loop POSTed an empty body at four guessed endpoints to see which returned 404. One of them was /api/core/system/reboot. It returned 200 because it rebooted the FV edge firewall, taking the whole site — including the BMC, which sits behind it — dark for 3.5 minutes. The call it was actually looking for is documented directly above, in § Service control, in this file.

• Read this reference and the upstream endpoint list first.
• If you must discover, use GET on a get/search/status command, never POST on an unknown name.
• Take /api/core/backup/download/this before any write. That part went right and is the only reason the change was reversible.

The one useful thing that fell out of it

POST /api/core/system/reboot with {} is a reliable remote reboot for the FV gateway — it came back cleanly on its own in ~3.5 min from an API-initiated restart, which is a capability worth knowing deliberately rather than by accident. /api/core/service/restart/<id> (e.g. openssh) restarts one service without the site outage, and is almost always what you want instead.

Applying a change — service/reconfigure, not a reboot

settings/set (and auth/user/set) write config.xml. They do not sync the change to the running system. The apply step is the module's service endpoint:

POST /api/<module>/service/reconfigure   {}

⚠ Some modules have no reconfigure and return {"errorMessage":"Endpoint not found"} — auth/user is one. For those the OS-level sync happens on the UI's own save path or at boot, so an API-only key edit sits in config.xml and does nothing until then. Verified 2026-09-15: authorizedkeys + shell for infra-ops persisted immediately but SSH kept refusing, and started working after a reboot completed the user sync.

⚠ POST with no body at all returns 411 Length Required. Send {}.

Field shapes — the part upstream does not document

⚠ A settings/get response is NOT a valid settings/set body. They are different shapes, and mixing them returns a bare {"errorMessage":"Unexpected error, check log for details"} with no indication of which field was wrong.

Selection / option fields. get returns every option with a selected flag; set wants only the selected key.

// get
"useExitNode": {"": {"value": "None", "selected": 1}, "abc": {"value":"node-a","selected":0}}
// set
"useExitNode": ""

Array / list fields are UUID-keyed objects, not lists. This is the one that costs an afternoon. get renders an empty array as [], which misleads you into POSTing a list.

// get, when empty  -> looks like a plain list
"subnets": {"subnet4": []}
// set  -> object keyed by a UUID you generate, values are the item's own fields
"subnets": {"subnet4": {"<uuid4>": {"subnet": "10.251.0.0/16", "description": "..."}}}

Discovering an array item's inner fields — two reliable tricks:

1. POST the wrong shape on purpose. Validation names the full path: {"result":"failed","validations":{"settings.subnets.subnet4.<uuid>.subnet":"A value is required."}}
2. Many models expose a template getter: /api/<module>/settings/get_<item> returns the blank item, e.g. get_subnet → {"subnet4":{"subnet":"","description":""}}

Partial set is supported — POST only the fields you are changing rather than round-tripping the whole model. This sidesteps every other field's shape problem and is the recommended approach for a surgical change.

Validation error format: {"result":"failed","validations":{"<dotted.path>":"<message>"}}. A successful save is {"result":"saved"}.

Working example — enabling a subnet router (2026-09-13, FV gateway)

POST /api/tailscale/settings/set
{"settings":{"enabled":"1",
  "subnets":{"subnet4":{"<uuid4>":{"subnet":"10.251.0.0/16",
                                   "description":"FV site subnet router"}}}}}
POST /api/tailscale/service/reconfigure   {}

Always read back. settings/get after the write, and re-check anything the change could disturb (here: /api/firewall/source_nat/search_rule total stayed at 2). A write that reports success is not evidence the value landed.

Related

• docs/runbooks/fv-to-ana-nat.md — the FV gateway's manual SNAT rule
• docs/runbooks/fv-site-dark-20260913.md — the outage this reference came out of