pfSense REST API: an unofficial REST and GraphQL layer for pfSense

A community API for a firewall that ships without one

pfSense REST API is described as an unofficial, open-source REST and GraphQL API for pfSense CE and pfSense Plus firewalls, and the design goal is stated as light-weight, fast and easy to use. The gap it fills is a familiar one in the pfSense world, where the console is a PHP web interface designed for a human in a browser and the configuration is a generated config file. Neither is pleasant to drive from an automation script or a monitoring system. The disclaimers section sets the most important fact about the project before anything else, and it repays reading in the original wording. The package is not affiliated with or supported by Netgate or the pfSense team, and it is developed and maintained by the community. That is a normal arrangement for a community package, but on a network edge device it changes how you should treat the component, since a security fix has to come from the community rather than from the firewall vendor.

Two hundred endpoints plus a GraphQL layer

The key features list is the real specification of the project. There are more than 200 REST endpoints for managing the firewall and its associated services, and a GraphQL API for flexible data retrieval and mutation, which is the interesting half for anyone who has tried to assemble a rich read model out of many small REST calls. Around those sit easier querying and filtering, configurable security settings, support for HATEOAS driven development, customizable authentication options, and built-in Swagger documentation. The GraphQL and REST sides are complementary rather than redundant, with REST staying the pragmatic interface for single object operations and configuration changes, and GraphQL covering the read heavy cases where a dashboard wants a lot of related data in one round trip. The Swagger documentation being built in rather than bolted on is what makes the API usable by a team that did not write it.

Installing on pfSense CE and on pfSense Plus

The package is installed with the pfSense package manager, and the two editions take slightly different commands because the Plus edition prompts for configuration. On pfSense CE:

pkg-static add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-2.8.1-pkg-RESTAPI.pkg

On pfSense Plus:

pkg-static -C /dev/null add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-26.03.1-pkg-RESTAPI.pkg

The tip attached to those commands is the important part, because the download path in the quickstart is a starting point rather than the answer. You may need to customize the command to reference the package built for your pfSense version, and the releases page is where you find the build that matches yours. The warning above it is blunt about the consequence of getting it wrong. Before installing, always ensure your pfSense version is supported, the supported list lives in the installation documentation, and installing the package on unsupported versions may result in unexpected behavior and system instability.

Authentication and the documentation you get for free

Four documentation pages are linked from the Getting Started section, and they map onto the questions an integrator actually has. Installation and Configuration covers putting the package on the box and pointing it at the right pfSense version. Authentication and Authorization covers the customizable authentication options and the configurable security settings listed in the features, which is the part that matters most on a firewall. Swagger and OpenAPI covers the built-in Swagger documentation, which is generated from the API definition rather than written by hand. Queries, Filters, and Sorting covers the retrieval side, and it is where the GraphQL and REST behaviours diverge enough to justify reading it in full. The Swagger and OpenAPI page and the spectral configuration in the repository together suggest the API definition is treated as a source artefact that is linted in CI, which is a better sign of maintenance discipline than a hand maintained document would be.

The repository is a package plus its documentation pipeline

The top level shows a project that maintains more than a PHP package. The pfSense-pkg-RESTAPI directory holds the package itself, and next to it sit docs, a tools directory, a Vagrantfile and vagrant-build.sh for building and testing the package on a throwaway machine, composer.json and composer.lock for the PHP dependencies, package.json and package-lock.json for the JavaScript side, mkdocs.yml for the documentation site, and phpdoc.dist.xml for the API reference. The linting configuration is spread across several tools, with .phplint.yml for PHP syntax, .pylintrc for the Python scripts, .prettierrc and .prettierignore for formatting with the prettier plugin for PHP, and .spectral.yml for linting the OpenAPI specification. The requirements file lists jinja2, pylint, black and mkdocs, which are the documentation and formatting toolchain, and the three GitHub Actions badges for build, quality and release show that all of it runs on every change.

Two release lines and a version-specific install

On the maintenance side, the release history is denser than a typical community project, with v2.10.2 and v2.10.1 both tagged on 2026-08-23 and v1.9.1 on 2026-08-22, so a 1.x line and a 2.x line are being shipped days apart. The last push was on 2026-10-20 and the repository is not archived, which is the pattern of an actively worked project rather than a one-off contribution. The licence is Apache 2.0, with the LICENSE file at the root. What the version scheme means in practice is the interesting part, and the README gives it away by building a separate package artefact per pfSense release, with a 2.8.1 build for CE and a 26.03.1 build for Plus in the quickstart alone. The package is therefore coupled to the firewall version underneath it, and the upgrade sequence is not just the package version, it is the package version matched to the pfSense version, with a matching build chosen from the releases page every time.

What to think about before putting an API on your firewall

There is a risk question that the documentation leaves to the adopter, and it deserves more than a sentence. An API that can read and mutate firewall configuration, reachable over HTTP and authenticated by credentials you configure, is a new attack surface on the device that sits at the edge of your network. The package gives you configurable security settings and customizable authentication, and the documentation points you at both, but the defaults are the operator's decision, and so is the decision about which networks may reach the endpoint. Combined with the unofficial status, the sensible pattern is to treat the API as an automation surface on a management network rather than on the untrusted side, to keep the credentials in the same hands as the firewall configuration, and to read the authentication documentation before the first call rather than after the first incident. The HATEOAS driven development support, where responses point at the resources that relate to them, makes it easy to write an agent that follows references and does more than the operator intended, which is another reason to keep the reachable scope narrow.

Editorial conclusion

pfSense REST API fits a network team that has pfSense in front of its users and wants firewall and service management available over HTTP for automation, inventory or self-service portals, and it suits teams that already treat pfSense configuration as code and want to query it rather than edit the config file. It is the wrong choice if you need vendor support, since the README states plainly that the package is not affiliated with or supported by Netgate or the pfSense team, and it is a poor fit if you cannot accept that the package is built per pfSense version, because a firewall upgrade may need a matching package build. Before you deploy it, check the supported pfSense versions list, confirm your automation can tolerate an unauthenticated-adjacent API surface on a firewall, and plan the upgrade path for the package itself.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. pfrest/pfSense-pkg-RESTAPI on GitHub
3. Project website
4. README
5. Releases