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: ""  # 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=""
export PIHOLE_API_TOKEN="your-app-password-here"
export PIHOLE_INSECURE="false"

Getting API Credentials

Open Pi-hole Admin at 2. Navigate to **Settings** > **API** 3. Generate an app password 4. 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_BLOCK_2__ ## API Endpoints (Pi-hole v6) ### Authentication __CODE_BLOCK_3__ ### Status __CODE_BLOCK_4__ ### Enable/Disable __CODE_BLOCK_5__ ### Stats __CODE_BLOCK_6__ ### Queries __CODE_BLOCK_7__ ## 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) __CODE_BLOCK_8__ ### Self-Signed/Local Cert __CODE_BLOCK_9__ 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)