Skip to content

Integrations

Ferrous DNS is built around a fully documented REST API, so any tool that speaks HTTP and understands OpenAPI can drive it. This page covers the built-in interactive API explorer (Swagger-style docs) and how to plug the OpenAPI specification into external tooling.

Interactive API Docs (Swagger / Scalar)

The server ships a built-in interactive API explorer rendered with Scalar — the same "try it in the browser" experience you get from Swagger UI. It is served on the web port (web_port, default 8080) and requires no authentication to open.

Mode OpenAPI spec Interactive docs
Normal http://<server>:8080/api/openapi.json http://<server>:8080/api/docs
Pi-hole compat (native API) http://<server>:8080/ferrous/api/openapi.json http://<server>:8080/ferrous/api/docs
Pi-hole compat (Pi-hole API) http://<server>:8080/api/openapi.json http://<server>:8080/api/docs

Scalar, not Swagger UI

The bundled UI is Scalar, which renders the same OpenAPI 3.x spec Swagger UI consumes. If you prefer Swagger UI specifically, point it at the openapi.json endpoint above — the spec is identical.

Using the OpenAPI Spec

The spec describes every handler, request/response schema, parameter, and security scheme (session_cookie + X-Api-Key for the native API, X-FTL-SID for the Pi-hole layer). Feed it into any OpenAPI-aware tool:

docker run -p 8081:8080 \
  -e SWAGGER_JSON_URL=http://<server>:8080/api/openapi.json \
  swaggerapi/swagger-ui

Import the collection from the spec URL: 

http://<server>:8080/api/openapi.json


openapi-generator-cli generate \
  -i http://<server>:8080/api/openapi.json \
  -g python \
  -o ./ferrous-client

schemathesis run http://<server>:8080/api/openapi.json \
  --header "X-Api-Key: your-token"

Authenticating from external tools

For programmatic access create an API token in the dashboard (or via the API Token endpoints) and send it in the X-Api-Key header. See Authentication for the full guard behaviour.

Pi-hole v6 API

When pihole_compat = true, Ferrous DNS also exposes a Pi-hole v6 compatible API at /api/*, so existing Pi-hole clients, mobile apps, and dashboards work unchanged. The native Ferrous API moves to /ferrous/api/* in this mode.

See Pi-hole Compatibility for the supported endpoints and behaviour.

See Also