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

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