API End Points

Overview

This documentation covers the available Pi-hole API endpoints, compiled through code analysis. Many of these endpoints were previously undocumented or poorly documented.

Base URL

http://<ip-address>/admin/api.php

Authentication

All endpoints require authentication using the auth parameter unless otherwise specified.

1. General Stats and System Info

These endpoints provide high-level system information and statistics:

• /admin/api.php?type=FTL - Retrieves FTL-specific data
• /admin/api.php?version - Gets the current version of Pi-hole components
• /admin/api.php?status - Retrieves Pi-hole's operational status
• /admin/api.php?summary - Provides a summary of system statistics
• /admin/api.php?summaryRaw - Returns raw system statistics data

2. Logs and Statistics

These endpoints provide access to system logs, query statistics, and performance metrics:

Query and Cache Information

• /admin/api.php?getMaxlogage - Gets the maximum log age in hours
• /admin/api.php?overTimeData10mins - Retrieves query stats aggregated into 10-minute intervals
• /admin/api.php?getCacheInfo - Provides DNS cache information
• /admin/api.php?getAllQueries=[filters] - Retrieves detailed query data with optional filters
  • Available filters: domain, client, querytype, forwarddest, from, until, or number

Top Items and Statistics

• /admin/api.php?topItems=[audit|number] - Lists top queried domains and ads blocked
• /admin/api.php?topClients=[number] - Shows the top clients by query count
• /admin/api.php?getQuerySources=[number] - Displays query sources by volume
• /admin/api.php?topClientsBlocked=[number] - Lists clients with the most blocked queries

Forwarding and Query Types

• /admin/api.php?getForwardDestinations=[unsorted] - Displays forward destination statistics
• /admin/api.php?getQueryTypes - Retrieves statistics on query types
• /admin/api.php?getForwardDestinationNames - Lists names of forward destinations
• /admin/api.php?overTimeDataQueryTypes - Displays query types over time

Client Information

• /admin/api.php?getClientNames - Lists all registered client names
• /admin/api.php?overTimeDataClients - Provides client activity over time
• /admin/api.php?recentBlocked - Shows the last blocked domain

3. Management and Configuration

System Management

• /admin/api.php?enable[&auth={token}]&token={CSRF} - Enables Pi-hole
• /admin/api.php?disable[&disable={seconds}]&auth={token}&token={CSRF} - Disables Pi-hole for a specified duration
• /admin/api.php?versions - Checks for Pi-hole updates

DNS and Lease Management

• /admin/api.php?delete_lease=[lease_id] - Deletes a specific DHCP lease
• /admin/api.php?dns-port - Retrieves or sets the DNS port configuration

Blacklist/Whitelist Management

Endpoint: /admin/api.php?list={type}[&add={domain}][&sub={domain}]

Supported Types:

• black - Blacklist
• regex_black - Regex Blacklist
• white - Whitelist
• regex_white - Regex Whitelist

Custom DNS Management

Endpoint: /admin/api.php?customdns&action={action}[&auth={token}]&token={CSRF}

Actions:

• get - Retrieve all custom DNS records
• add - Add a new custom DNS entry
• delete - Delete a custom DNS entry

Custom CNAME Management

Endpoint: /admin/api.php?customcname&action={action}[&auth={token}]&token={CSRF}

Actions:

• get - Retrieve all CNAME records
• add - Add a new CNAME record
• delete - Delete a CNAME record

Additional Information

Response Format Options

• Use jsonForceObject=true to force JSON objects in responses

Security Notes

• API calls require authentication using auth={token} or CSRF validation with token={CSRF}

Data Filtering

• Many endpoints support optional query parameters for filtering or modifying the returned data

Disclaimer

This documentation is based on reverse-engineering the Pi-hole source code and may not reflect future API changes.