Using curl with the Pihole API

I couldn’t find any quick references about accessing the Pihole API so I created this page.

Pihole is a great app for blocking internet advertising that was originally designed to be run on a raspberry pi. It blocks known advertisers’ domains at the DNS level by effectively null routing requests destined to serve ads. It can be run on VMs, Raspberry Pis and bare metal servers.

Here are the steps to access the pihole’s rest api. I’m using curl in this example, but you can integrate it with OpenHAB or any other system that can talk REST.

Step 1: Obtaining the web password

Most of the useful API endpoints the pihole provides wisely require authentication. After searching around the net I found that I could pass &token=A_VALID_SESSION_TOKEN to authenticate to the pihole for a session. Unfortunately, this is a temporary auth token and wasn’t suitable for my needs. After more digging, I found the gem I needed: &auth=WEBPASSWORD. Sounds great, but where do I obtain this password? You simply log onto your pihole instance or server and run:

sudo cat /etc/pihole/setupVars.conf | grep PASSWORD
17d1ce58eb420998d69dfd2850e7c639706715335d78447f78723489df78234

How convenient. It’s stored right there in the Piholes vars config file. Copy this password (hash, base64encoded string, whatever you want to call it)

Step 2: Create an API call using the password

I’m using curl and the ultra useful jq commands in my scripts. If you don’t have jq and work with anything JSON you should probably install it.

Refer to the official pihole api documentation here.

Step 3: Sample curls and output (the password has been obfuscated)

Substitute your.pihole.address with the IP or hostname of your Pihole and the auth=956e54... with your Pihole’s WEBPASSWORD

overTimeData10mins

curl -ks "https://your.pihole.address/admin/api.php?overTimeData10mins&auth=956e54sdfsd1ce58eb420998sdfd69dfd2839706715335d78447f7db4cd7f6e"
{
  "domains_over_time": 
    {
      "1529553900": 806,
      "1529554500": 810,
      "1529555100": 899,
      "1529555700": 145
    },
 "ads_over_time": 
   {
     "1529553900": 100,
     "1529554500": 209,
     "1529555100": 202,
     "1529555700": 51
   }
}

View List of configured forward destinations

curl -ks "https://your.pihole.address/admin/api.php?getForwardDestinations&auth=956e54sdfsd1ce58eb420998sdfd69dfd2839706715335d78447f7db4cd7f6e"
{
  "forward_destinations": {
    "local|::1": 77.55,
    "1dot1dot1dot1.cloudflare-dns.com|1.1.1.1": 19.3,
    "dns.quad9.net|9.9.9.9": 3.16
  }
}

Now you can integrate shell scripts, your own apps or other services with the Pihole via it’s API. I’m using it for my executive dashboard and this is the PiHole specific component.