Pi-hole API: Automate and Manage via REST API (2026)

The Pi-hole API is a RESTful interface that lets you programmatically control and query your Pi-hole instance, turning it into a manageable network service rather than just a GUI-driven appliance.

Let’s see it in action. Imagine you want to disable Pi-hole for 5 minutes to test if ads are returning. Without the API, you’d log into the web interface, click "Disable," select "5 minutes," and click again. With the API, it’s a single command:

curl "http://pi.hole/admin/api.php?disable=300&auth=YOUR_API_TOKEN"

This command sends a GET request to the Pi-hole API endpoint. The disable=300 parameter tells Pi-hole to disable blocking for 300 seconds (5 minutes), and auth=YOUR_API_TOKEN is your authentication credential. The response will be a JSON object indicating success:

{
    "success": true,
    "message": "Pi-hole disabled for 300 seconds."
}

You can re-enable it immediately with another command:

curl "http://pi.hole/admin/api.php?enable=all&auth=YOUR_API_TOKEN"

This enable=all parameter tells Pi-hole to resume blocking for all configured ad lists. The response:

{
    "success": true,
    "message": "Pi-hole enabled."
}

The API exposes a wealth of information and control. You can query the current status, get statistics, manage blocklists, and even trigger updates.

Here’s how you can get a summary of your Pi-hole’s current state:

curl "http://pi.hole/admin/api.php?summary=yes&auth=YOUR_API_TOKEN"

The output will be a JSON object like this:

{
    "summary_raw": {
        "total_queries": 123456,
        "total_blocked": 7890,
        "total_not_blocked": 115566,
        "dns_queries_today": 5000,
        "unique_clients": 25,
        "ads_percentage_today": 15.78
    },
    "status": "enabled"
}

This gives you real-time insights into your network’s DNS activity and Pi-hole’s effectiveness.

You can also fetch the list of currently blocked domains:

curl "http://pi.hole/admin/api.php?getBanned=1&auth=YOUR_API_TOKEN"

The response will be a JSON object containing an array of banned domains, each with its addition date:

{
    "Banned_Ad_Domains": [
        {
            "domain": "doubleclick.net",
            "added": "2023-10-27 10:00:00"
        },
        {
            "domain": "googleadservices.com",
            "added": "2023-10-27 10:05:00"
        }
    ]
}

To add a domain to the blocklist:

curl "http://pi.hole/admin/api.php?addBanned=mycustomad.com&auth=YOUR_API_TOKEN"

And to remove it:

curl "http://pi.hole/admin/api.php?deleteBanned=mycustomad.com&auth=YOUR_API_TOKEN"

The auth token is crucial for security. You can generate this token in the Pi-hole web interface under Settings -> API / Web interface. It’s a long alphanumeric string that acts as your password for API access. Keep it secure!

The API is built around simple GET requests with query parameters that dictate the action. For enabling/disabling, the parameters are enable and disable, accepting values like all (for enabling) or a number of seconds (for disabling). For data retrieval, parameters like summary, getBanned, getForwardDestinations, and getDomainInfo are used. You can also trigger actions like update to force an update of the blocklists.

One powerful, yet often overlooked, aspect of the API is its ability to retrieve detailed query logs. While summary gives you aggregates, get_logs (though not directly exposed as a simple GET parameter in the same way as others for security and performance reasons) can be accessed by more advanced scripting or by querying the underlying database if needed. However, for most common scripting tasks, the available GET parameters are sufficient. The getDomainInfo parameter, for instance, is excellent for checking the status of a specific domain: curl "http://pi.hole/admin/api.php?getDomainInfo=example.com&auth=YOUR_API_TOKEN". This returns whether the domain is blocked, cached, or permitted.

The API is a fundamental tool for integrating Pi-hole into larger network management solutions, home automation systems, or for custom monitoring dashboards. It allows for the creation of sophisticated workflows that react to network conditions or perform scheduled maintenance tasks without manual intervention.

The next step you’ll likely explore is how to leverage the API within a scripting language like Python or Bash to create more complex automation.