Pi-hole Skill
Control your Pi-hole DNS ad blocker via the Pi-hole v6 API.
Setup
Set your Pi-hole API configuration in Clawdbot config:
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:
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
# 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
POST /api/auth
Content-Type: application/json
{"password":"your-app-password"}
Response:
{
"session": {
"sid": "session-token-here",
"validity": 1800
}
}
Status
GET /api/dns/blocking
Headers: sid: <session-token>
Response:
{
"blocking": "enabled" | "disabled",
"timer": 30 // seconds until re-enable (if disabled with timer)
}
Enable/Disable
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
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
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)
{
"apiUrl": "https://pi-hole.example.com/api",
"apiToken": "...",
"insecure": false
}
Self-Signed/Local Cert
{
"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 clawdbot'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)
