README

The Pi-hole API is organized around REST. Our API has predictable resource-oriented URLs, accepts and returns reliable UTF-8 JavaScript Object Notation (JSON)-encoded data for all API responses, and uses standard HTTP response codes and verbs. Most (but not all) endpoints require authentication. API endpoints requiring authentication will fail with code 401 Unauthorized when used outside a valid session.

For more information, please visit https://discourse.pi-hole.net.

Installation & Usage

Requirements

PHP 8.1 and later.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/aseemann/pihole-api-client.git"
    }
  ],
  "require": {
    "aseemann/pihole-api-client": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/aseemann/pihole-api-client/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure API key authorization: x_header_sid
$config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKey('X-FTL-SID', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-FTL-SID', 'Bearer');

// Configure API key authorization: query_sid
$config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKey('sid', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('sid', 'Bearer');

// Configure API key authorization: cookie_sid
$config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKey('sid', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('sid', 'Bearer');

// Configure API key authorization: header_sid
$config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKey('sid', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('sid', 'Bearer');


$apiInstance = new Aseemann\PiholeApi\Api\ActionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

try {
    $result = $apiInstance->actionFlusharp();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ActionsApi->actionFlusharp: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://pi.hole:443/api

Class	Method	HTTP request	Description
ActionsApi	actionFlusharp	POST /action/flush/arp	Flush the network table
ActionsApi	actionFlushlogs	POST /action/flush/logs	Flush the DNS logs
ActionsApi	actionGravity	POST /action/gravity	Run gravity
ActionsApi	actionRestartdns	POST /action/restartdns	Restart pihole-FTL
AuthenticationApi	addApp	GET /auth/app	Create new application password
AuthenticationApi	addAuth	POST /auth	Submit password for login
AuthenticationApi	deleteAuthSession	DELETE /auth/session/{id}	Delete session by ID
AuthenticationApi	deleteGroups	DELETE /auth	Delete session
AuthenticationApi	getAuth	GET /auth	Check if authentication is required
AuthenticationApi	getAuthSessions	GET /auth/sessions	List of all current sessions
AuthenticationApi	getAuthTotp	GET /auth/totp	Suggest new TOTP credentials
ClientManagementApi	addClient	POST /clients	Add new client
ClientManagementApi	batchDeleteClients	POST /clients:batchDelete	Delete multiple clients
ClientManagementApi	deleteClient	DELETE /clients/{client}	Delete client
ClientManagementApi	getClientSuggestions	GET /clients/_suggestions	Get client suggestions
ClientManagementApi	getClients	GET /clients/{client}	Get clients
ClientManagementApi	replaceClient	PUT /clients/{client}	Replace client
DHCPApi	deleteDhcp	DELETE /dhcp/leases/{ip}	Remove DHCP lease
DHCPApi	getDhcp	GET /dhcp/leases	Get currently active DHCP leases
DNSControlApi	getBlocking	GET /dns/blocking	Get current blocking status
DNSControlApi	setBlocking	POST /dns/blocking	Change current blocking status
DocumentationApi	getDocs	GET /docs	Get the embedded API documentation rendered as HTML
DomainManagementApi	addDomain	POST /domains/{type}/{kind}	Add new domain
DomainManagementApi	batchDeleteDomains	POST /domains:batchDelete	Delete multiple domains
DomainManagementApi	deleteDomain	DELETE /domains/{type}/{kind}/{domain}	Delete domain
DomainManagementApi	getDomains	GET /domains/{type}/{kind}/{domain}	Get domain
DomainManagementApi	replaceDomain	PUT /domains/{type}/{kind}/{domain}	Replace domain
FTLInformationApi	deleteMessage	DELETE /info/messages/{message_id}	Delete Pi-hole diagnosis message
FTLInformationApi	getClient	GET /info/client	Get information about requesting client
FTLInformationApi	getDbinfo	GET /info/database	Get info about long-term database
FTLInformationApi	getDnsLog	GET /logs/dnsmasq	Get DNS log content
FTLInformationApi	getEndpoints	GET /endpoints	Get list of available API endpoints
FTLInformationApi	getFtlLog	GET /logs/ftl	Get DNS log content
FTLInformationApi	getFtlinfo	GET /info/ftl	Get info about various ftl parameters
FTLInformationApi	getHostinfo	GET /info/host	Get info about various host parameters
FTLInformationApi	getLogininfo	GET /info/login	Login page related information
FTLInformationApi	getMessages	GET /info/messages	Get Pi-hole diagnosis messages
FTLInformationApi	getMessagesCount	GET /info/messages/count	Get count of Pi-hole diagnosis messages
FTLInformationApi	getMetricsinfo	GET /info/metrics	Get metrics info
FTLInformationApi	getSensors	GET /info/sensors	Get info about various sensors
FTLInformationApi	getSysteminfo	GET /info/system	Get info about various system parameters
FTLInformationApi	getVersion	GET /info/version	Get Pi-hole version
FTLInformationApi	getWebserverLog	GET /logs/webserver	Get DNS log content
GroupManagementApi	addGroup	POST /groups	Add new group
GroupManagementApi	batchDeleteGroups	POST /groups:batchDelete	Delete multiple groups
GroupManagementApi	deleteGroup	DELETE /groups/{name}	Delete group
GroupManagementApi	getGroups	GET /groups/{name}	Get groups
GroupManagementApi	replaceGroup	PUT /groups/{name}	Replace group
ListManagementApi	addList	POST /lists	Add new list
ListManagementApi	batchDeleteLists	POST /lists:batchDelete	Delete lists
ListManagementApi	deleteLists	DELETE /lists/{list}	Delete list
ListManagementApi	getLists	GET /lists/{list}	Get lists
ListManagementApi	getSearch	GET /search/{domain}	Search domains in Pi-hole's lists
ListManagementApi	replaceLists	PUT /lists/{list}	Replace list
MetricsApi	getActivityMetrics	GET /history	Get activity graph data
MetricsApi	getActivityMetricsDatabase	GET /history/database	Get activity graph data (long-term data)
MetricsApi	getClientMetrics	GET /history/clients	Get per-client activity graph data
MetricsApi	getClientMetricsDatabase	GET /history/database/clients	Get per-client activity graph data (long-term data)
MetricsApi	getMetricsDatabaseQueryTypes	GET /stats/database/query_types	Get query types (long-term database)
MetricsApi	getMetricsDatabaseSummary	GET /stats/database/summary	Get database content details
MetricsApi	getMetricsDatabaseTopClients	GET /stats/database/top_clients	Get top clients (long-term database)
MetricsApi	getMetricsDatabaseTopDomains	GET /stats/database/top_domains	Get top domains (long-term database)
MetricsApi	getMetricsQueryTypes	GET /stats/query_types	Get query types
MetricsApi	getMetricsRecentBlocked	GET /stats/recent_blocked	Get most recently blocked domain
MetricsApi	getMetricsSummary	GET /stats/summary	Get overview of Pi-hole activity
MetricsApi	getMetricsTopClients	GET /stats/top_clients	Get top clients
MetricsApi	getMetricsTopDomains	GET /stats/top_domains	Get top domains
MetricsApi	getMetricsUpstreams	GET /stats/upstreams	Get metrics about Pi-hole's upstream destinations
MetricsApi	getMetricsUpstreamsDatabase	GET /stats/database/upstreams	Get metrics about Pi-hole's upstream destinations (long-term database)
MetricsApi	getQueries	GET /queries	Get queries
MetricsApi	getSuggestions	GET /queries/suggestions	Get query filter suggestions
NetworkInformationApi	deleteDevice	DELETE /network/devices/{device_id}	Delete a device from the network table
NetworkInformationApi	getGateway	GET /network/gateway	Get info about the gateway of your Pi-hole
NetworkInformationApi	getInterfaces	GET /network/interfaces	Get info about the interfaces of your Pi-hole
NetworkInformationApi	getNetwork	GET /network/devices	Get info about the devices in your local network as seen by your Pi-hole
NetworkInformationApi	getRoutes	GET /network/routes	Get info about the routes of your Pi-hole
PADDApi	getPadd	GET /padd	Get summarized data for PADD
PiHoleConfigurationApi	addArrayItem	PUT /config/{element}/{value}	Add config array item
PiHoleConfigurationApi	deleteArrayItem	DELETE /config/{element}/{value}	Delete config array item
PiHoleConfigurationApi	getConfig	GET /config	Get current configuration of your Pi-hole
PiHoleConfigurationApi	getConfigElem	GET /config/{element}	Get specific part of current configuration of your Pi-hole
PiHoleConfigurationApi	getTeleporter	GET /teleporter	Export Pi-hole settings
PiHoleConfigurationApi	patchConfig	PATCH /config	Change configuration of your Pi-hole
PiHoleConfigurationApi	postTeleporter	POST /teleporter	Import Pi-hole settings

Models

Authorization

Authentication schemes defined for the API:

query_sid

Type: API key
API key parameter name: sid
Location: URL query string

cookie_sid

Type: API key
API key parameter name: sid
Location:

header_sid

Type: API key
API key parameter name: sid
Location: HTTP header

x_header_sid

Type: API key
API key parameter name: X-FTL-SID
Location: HTTP header

query_password

Type: API key
API key parameter name: password
Location: URL query string

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

API version: 6.0
- Generator version: 7.13.0-SNAPSHOT
Build package: org.openapitools.codegen.languages.PhpClientCodegen

aseemann / pihole-api-client

Maintainers

Details