Pi-hole API

If there was a RESTful (or similar) API, it would open the world to accessing the Pi-hole. A developer could write an extension that could turn the Pi-hole off and on; add sites to the white and blacklist or change the blocklists.

The two way nature of an API could be useful in showing stats without having the need to have a web browser open.

I always love doing this:


Work in progress :wink:

For the shell lovers:

pi@noads:~ $ surfraw duckduckgo -l pihole restful api
Announcing Our RESTful API — Contributions Welcome – Pi-hole®: A blac (p1 of 9)
   Link: profile
   Link: prev: What Really Happens On Your Network? Part Eight
   Link: next: Pi-hole As A Snapcraft Package
   Link: canonical
   Link: shortlink
   Pi-hole®: A black hole for Internet advertisements
     * GitHub
          * Core
          * Web
          * FTL
          * API
          * Docker
     * Community
          * Log in with Discourse
          * My Account
          * Discourse
          * Reddit
          * Twitter
     * About
          * Documentation
          * Contact
          * Privacy

From the readme.md:
Work in progress HTTP API for Pi-hole. It accesses the internal FTL API through a Unix domain socket

Domain sockets only work on the server. What I was meaning was something like:


So a 3rd party developer could access the Pi-hole remotely with a shared key and secret.


"the API will host the Web interface"
"The API exposes a RESTful HTTP API which is used by the web interface"

Yes oc a socket, the TCP 80 or 443 one :wink:

There is more information and up to date code available on the development branch: GitHub - pi-hole/api at development

This API does host a HTTP interface. An example request would be:

GET http://pi.hole/admin/api/stats/summary
X-Pi-hole-Authenticate: <secret_here>

Response (dev server, so not many blocked queries):

  "active_clients": 1,
  "blocked_queries": 0,
  "cached_queries": 0,
  "forwarded_queries": 33442,
  "gravity_size": 112866,
  "percent_blocked": 0.0,
  "reply_types": {
    "CNAME": 0,
    "DOMAIN": 0,
    "IP": 0,
    "NODATA": 0,
    "NXDOMAIN": 0
  "status": "enabled",
  "total_clients": 1,
  "total_queries": {
    "A": 16673,
    "AAAA": 16673,
    "ANY": 0,
    "PTR": 96,
    "SOA": 0,
    "SRV": 0,
    "TXT": 0
  "unique_domains": 16

API Endpoints for list manipulations in pihole v5.0