How to use the api

Help Community Help
1

I'm looking to automate a few domains on my blacklist for which I was hoping to use the API. Where can I find documentation on this topic? I have tried posting to /admin/scripts/pi-hole/php/groups.php using cURL, but this gives me "Not allowed (login session invalid or expired, please relogin on the Pi-hole dashboard)!". I have found the API token and this endpoint: /admin/api.php?status

1 Like
2

To use most API endpoints you need to append &auth=<YOURAPITOKEN> to the URL, like this:

http://pi.hole/admin/api.php?summaryRaw&auth=<YOURAPITOKEN>
3

Yes, I figured that, but where do I find info on the endpoints?

4

Here: Telnet API - Pi-hole documentation

5

So I guess it's not possible to block domains using the API? At least, I don't see any endpoints suggesting this.

6

I believe the API at api.php and the telnet API in pihole-FTL are two different things. The telnet API link above is for the latter. You are asking about the former and I don't think any documentation exists. There are scattered posts containing info and links to the source. Note recent changes since then, such as requiring authorisation on the API calls.

Edit: actually I'm not sure they are different or whether api.php ultimately pulls from the same pihole-FTL API. Can anyone clarify the API workflows and what documentation does and doesn't exist?

7

Thank you for clarifying this. Think I'll go with an automated/custom blocklist then instead of working with the API.

8

The PHP API is basically the way to use the telnet API endpoints inside PHP pages, but there are a few naming differences for the endpoints.

To understand the relation between them, you can look at the api.php and api_FTL.php code. PHP uses callFTLAPI() function to call FTL telnet endpoints.

As an example, the maxlogage FTL endpoint is called getMaxlogage on the PHP API.

if (isset($_GET['getMaxlogage']) && $auth) {
    $return = callFTLAPI('maxlogage');
    ...
1 Like
9

chrislph is correct, there is no good documentation for the current PHP API. You basically need to read the source code the figure out which endpoints exist.
We are working on Pi-hole v6 quite hard, which will have a new and extensive API. The API contains the documentation within itself and we added tests that will fail if an endpoint exists without documentation.

To get an idea what will be possible, have a look here: Pi-hole API documentation and especially: Pi-hole API documentation

(API is still a moving target - things can an will change probably still a lot)

1 Like
10

Thanks, the new API looks very comprehensive! That second endpoints link, should the TRY button be retrieving endpoints from a live API codebase? It reports "Response Status: Load failed (CORS or Network Issue)". Can you explain what this very slick interactive page is, is it a developer resource or an example the new API self-contained documentation?

11

It's an example of the new API documentation.

1 Like
12

It's both. It's a documentation for developers but also the new API self-contained documentation. Once you use FTL v6 this documentation is available on every Pi-hole installation and the documentation will always be in sync with your currently installed version. You can then use the "Login" to really login (authenticate) with your local FTL and "try" will actually send the API query to your Pi-hole.

15

This topic was automatically closed 21 days after the last reply. New replies are no longer allowed.