Support OpenAPI JSON spec at `/api/docs` via `Accept: application/json`

Feature Requests
1

Description:

Currently, accessing https://pihole.local/api/docs returns an HTML document regardless of the Accept header. This is useful for human-readable documentation but not for programmatic or CLI use.

Request:

Please add support for serving the OpenAPI (Swagger) spec at /api/docs when the request includes:

Accept: application/json

This would allow API tooling (e.g., curl, Postman, or OpenAPI generators) to consume the spec directly. Ideally, the spec should conform to OpenAPI 3.0 or 3.1.

Use Cases:

  • CLI tools could introspect the API schema
  • Automated documentation generation
  • SDK generation for multiple languages
  • Integration with tools like Postman or Swagger UI without manual intervention

Current Behavior:

curl -H "Accept: application/json" https://pihole.local/api/docs
# Returns HTML, not JSON

Proposed Behavior:

curl -H "Accept: application/json" https://pihole.local/api/docs
# Returns OpenAPI 3.0+ JSON schema

Thank you for considering this! Happy to help contribute a patch if this is something the team is open to.

2

See http://pi.hole/api/docs/specs/main.yaml

I don't think it's very logic to do this at such an almost arbitrary looking endpoint. Do you have any recommendations actually saying that'd be a common thing?

3

Thanks for the response. I didn’t realize the spec was available at /api/docs/specs/main.yaml. That wasn’t immediately obvious from the docs page, and I suspect others (especially CLI users or API tooling authors) might miss it unless it’s explicitly referenced.

Would you be open to one of the following?

  • Linking directly to /api/docs/specs/main.yaml from the /api/docs HTML page
  • Adding a GET /api/docs/spec endpoint that returns the spec
    • (optionally supporting a ?format=json or ?format=yaml query parameter)

I’d be happy to contribute a patch for either approach. Thanks again!

4

You mean as in adding a text that simply says where to find the specs? Yes, that's probably the only feasible idea here because main.yaml has references to other yaml files and if we'd only magically reveal the main.yaml file here, the clients would not be able to find the referenced other files they will need for the actual definitions.

This will be quite some work because of aforementioned referencing of other files. Such an endpoint would then need to resolve the references and inject them at the right places. For a conversion, be aware that while Pi-hole's API has full JSON functionality, there is currently no yaml interpreter available. This would be quite a massive endeavor for something I doubt would be used all that often.