Pi-hole Skill

Control your Pi-hole DNS ad blocker via the Pi-hole v6 API.

Setup

Set your Pi-hole API configuration in ThinkFleetBot config:

yaml

skills:
  entries:
    pihole:
      apiUrl: "https://pi-hole.local/api"  # v6 API path
      apiToken: "your-app-password-here"       # Get from Pi-hole Admin
      insecure: false                          # Set to true for self-signed certs

Alternatively, set environment variables:

bash

export PIHOLE_API_URL="https://pi-hole.local/api"
export PIHOLE_API_TOKEN="your-app-password-here"
export PIHOLE_INSECURE="false"

Getting API Credentials

•Open Pi-hole Admin at http://pi-hole.local/admin
•Navigate to Settings > API
•Generate an app password
•Use that password as apiToken

Capabilities

Status

•Get current Pi-hole status (enabled/disabled)
•View stats: queries blocked, queries today, domains being blocked, active clients
•See recent query activity

Controls

•Enable/Disable: Turn Pi-hole on or off
•Disable for 5 minutes: Temporarily disable ad blocking for a short period
•Disable for custom duration: Set specific disable time (in minutes)

Block Analysis

•Check blocked domains: See what domains were blocked in a time window
•Show top blocked: Most frequently blocked domains

Usage Examples

code

# Check Pi-hole status
"pihole status"

# Turn off ad blocking
"pihole off"

# Turn on ad blocking
"pihole on"

# Disable for 5 minutes (for a site that needs ads)
"pihole disable 5m"

# Disable for 30 minutes
"pihole disable 30"

# See what was blocked in the last 30 minutes
"pihole blocked"

# See blocked domains in last 10 minutes (600 seconds)
"pihole blocked 600"

# Show statistics
"pihole stats"

API Endpoints (Pi-hole v6)

Authentication

code

POST /api/auth
Content-Type: application/json
{"password":"your-app-password"}

Response:
{
  "session": {
    "sid": "session-token-here",
    "validity": 1800
  }
}

Status

code

GET /api/dns/blocking
Headers: sid: <session-token>

Response:
{
  "blocking": "enabled" | "disabled",
  "timer": 30  // seconds until re-enable (if disabled with timer)
}

Enable/Disable

code

POST /api/dns/blocking
Headers: sid: <session-token>
Content-Type: application/json

Enable:
{"blocking":true}

Disable:
{"blocking":false}

Disable with timer (seconds):
{"blocking":false,"timer":300}

Stats

code

GET /api/stats/summary
Headers: sid: <session-token>

Response:
{
  "queries": {
    "total": 233512,
    "blocked": 23496,
    "percent_blocked": 10.06
  },
  "gravity": {
    "domains_being_blocked": 165606
  },
  "clients": {
    "active": 45
  }
}

Queries

code

GET /api/queries?start=-<seconds>
Headers: sid: <session-token>

Response:
{
  "queries": [
    {
      "domain": "example.com",
      "status": "GRAVITY",
      "time": 1768363900,
      "type": "A"
    }
  ]
}

v5 vs v6 API Changes

Pi-hole v6 introduced significant API changes:

Feature	v5 API	v6 API
Base URL	`/admin/api.php`	`/api`
Auth	Token in URL/headers	Session-based
Status	`?status`	`/api/dns/blocking`
Stats	`?summaryRaw`	`/api/stats/summary`
Queries	`?recentBlocked`	`/api/queries`
Whitelist	Supported via API	Not available via API

Important: Domain whitelisting is no longer available via the v6 API. You must whitelist domains through the Pi-hole Admin UI.

SSL Certificates

Production (Valid Cert)

yaml

{
  "apiUrl": "https://pi-hole.example.com/api",
  "apiToken": "...",
  "insecure": false
}

Self-Signed/Local Cert

yaml

{
  "apiUrl": "https://pi-hole.local/api",
  "apiToken": "...",
  "insecure": true
}

The insecure flag adds the -k option to curl to bypass certificate validation.

Security Notes

•Session tokens expire after 30 minutes (1800 seconds)
•API password is sent in JSON body, not URL
•All requests have a 30-second timeout
•Token is not visible in process list (passed via environment)

Troubleshooting

"Failed to authenticate"

•Check that apiToken matches your Pi-hole app password
•Verify apiUrl is correct (must end in /api)
•Ensure Pi-hole is accessible from your network

"Could not determine status"

•Check API URL is reachable
•If using HTTPS with self-signed cert, set insecure: true
•Verify API password is correct

Network Errors

•Ensure thinkfleetbot's machine can reach the Pi-hole
•Check firewall rules allow API access
•Verify URL scheme (http vs https)

Requirements

•Pi-hole v6 or later
•App password generated in Pi-hole Admin
•Network access to Pi-hole API
•curl, jq (installed on most Unix systems)