# Scope of the v6 API includes DNS / CNAME CRUD?

**URL:** <https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373>\
**Category:** Beta 6.0\
**Created:** [October 10, 2024, 8:40am UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373 "2024-10-10T08:40:22Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![wzzrd](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/wzzrd/32/43701_2.png) [@wzzrd](https://discourse.pi-hole.net/u/wzzrd)\
**Post date:** [October 10, 2024, 8:40am UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/1 "2024-10-10T08:40:22Z")

</div>

Hey,

(Sorry I'm not really sure where to look for this info)

Will v6 have a "full" API, meaning that it will be possible to perform all tasks, including creating e.g. DNS records and CNAME records through it eventually? I would see a great use case for that for adding those records through automation (e.g. Ansible)

---

<div class="post-metadata">

**Author:** ![wzzrd](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/wzzrd/32/43701_2.png) [@wzzrd](https://discourse.pi-hole.net/u/wzzrd)\
**Post date:** [October 10, 2024, 9:00am UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/2 "2024-10-10T09:00:49Z")

</div>

I did find the current API docs for v6 beta, btw, and that does not show DNS record management as an option, so question still stands 🙂

---

<div class="post-metadata">

**Author:** ![yubiuser](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/yubiuser/32/12100_2.png) [@yubiuser](https://discourse.pi-hole.net/u/yubiuser)\
**Post date:** [October 10, 2024, 9:11am UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/3 "2024-10-10T09:11:14Z")

</div>

It should be in `/config` with `dns.hosts`

---

<div class="post-metadata">

**Author:** ![wzzrd](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/wzzrd/32/43701_2.png) [@wzzrd](https://discourse.pi-hole.net/u/wzzrd)\
**Post date:** [October 10, 2024, 9:46am UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/4 "2024-10-10T09:46:00Z")

</div>

Ah great, though that looks like a difficult to use API endpoint. This way, DNS record management (and DHCP lease management) is almost hidden away in a corner of the general settings API endpoint.

I had hoped it would be more like

`/dns/A/${host}/${ip}` and `/dns/CNAME/${alias}/${host}` or something like that, that would be a lot easier to do CRUD on, and DNS records would be a first class object that way

---

<div class="post-metadata">

**Author:** ![deHakkelaar](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/dehakkelaar/32/674_2.png) [@deHakkelaar](https://discourse.pi-hole.net/u/deHakkelaar)\
**Post date:** [October 10, 2024, 12:03pm UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/5 "2024-10-10T12:03:02Z")

</div>

> [@wzzrd](#):
>
> I had hoped it would be more like
> 
> `/dns/A/${host}/${ip}` and `/dns/CNAME/${alias}/${host}` or something like that

You're close:

```auto
$ curl -s --request PUT localhost/api/config/dns/hosts/10.10.10.10%20test | jq
{
  "took": 0.00929856300354004
}

```

```auto
$ curl -s localhost/api/config/dns/hosts | jq
{
  "config": {
    "dns": {
      "hosts": [
        "10.10.10.10 test"
      ]
    }
  },
  "took": 6.41345977783203e-05
}

```

```auto
$ dig +short @localhost test
10.10.10.10

```

```auto
$ curl -s --request PUT localhost/api/config/dns/cnameRecords/alias,pi.hole,330 | jq
{
  "took": 0.04300665855407715
}

```

```auto
$ curl -s localhost/api/config/dns/cnameRecords | jq
{
  "config": {
    "dns": {
      "cnameRecords": [
        "alias,pi.hole,0330"
      ]
    }
  },
  "took": 5.4836273193359375e-05
}

```

```auto
$ dig +short @localhost alias cname
pi.hole.

```

If want to see whats all in **config** :

`curl -s localhost/api/config | jq`

Or HTTPS:

`curl -s https://localhost/api/config | jq`

Or HTTPS with a self signed cert:

`curl -ks https://localhost/api/config | jq`

---

<div class="post-metadata">

**Author:** ![wzzrd](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/wzzrd/32/43701_2.png) [@wzzrd](https://discourse.pi-hole.net/u/wzzrd)\
**Post date:** [October 10, 2024, 12:56pm UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/6 "2024-10-10T12:56:50Z")

</div>

Oh that's actually much better than I thought 🙂

Any idea on whether you can GET a single record (`/api/config/dns/hosts/test` or `/api/config/dns/hosts/10.10.10.10`)? How do you DELETE a record? Send a DELETE to `/api/config/dns/hosts/test` or send the whole JSON structure with all records, minus the one I want to delete, to `/api/config/dns/hosts`?

---

<div class="post-metadata">

**Author:** ![DL6ER](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/dl6er/32/281_2.png) [@DL6ER](https://discourse.pi-hole.net/u/DL6ER)\
**Post date:** [October 10, 2024, 7:07pm UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/8 "2024-10-10T19:07:38Z")

</div>

You said you already found the API documentation. It is abstract but it is this only to be generic and complete. Whenever you click on the individual endpoints, you will see examples.

In general, the API really follows the REST principle so, when you create an item using

> [@deHakkelaar](#):
>
> `PUT localhost/api/config/dns/hosts/10.10.10.10%20test`

yous should be able to undo this with  
`DELETE localhost/api/config/dns/hosts/10.10.10.10%20test`

As the HTTP standard does not allow `DELETE` to have any payload, you can see the result based on the returned HTTP status code. All possible codes are described in the API documentation:

 ![image](https://discourse.pi-hole.net/uploads/default/original/3X/c/e/ce14fe387ce1f41799278b5d4441629ac21ceaf9.png)

> [@wzzrd](#):
>
> Any idea on whether you can GET a single record (`/api/config/dns/hosts/test` or `/api/config/dns/hosts/10.10.10.10`)?

This is not available. The reason is that you'd have to know the **exact** entry (in the example we're using here that'd be `"10.10.10.10%20test"`) and - in case you know that - the entire `GET` request is pointless. Usually, all config endpoints are manipulated only through `PATCH` (like editing the file), Pi-hole adds the `PUT` and `DELETE` options for you pure convenience to those config options which are of type "array of strings" to ease handling from external scripts (no JSON parsing required).

---

<div class="post-metadata">

**Author:** ![deHakkelaar](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/dehakkelaar/32/674_2.png) [@deHakkelaar](https://discourse.pi-hole.net/u/deHakkelaar)\
**Post date:** [October 11, 2024, 12:16am UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/9 "2024-10-11T00:16:06Z")

</div>

> [@wzzrd](#):
>
> Any idea on whether you can GET a single record (`/api/config/dns/hosts/test` or `/api/config/dns/hosts/10.10.10.10`)?

You can query with the JSON parser instead.  
From below examples:

[https://www.baeldung.com/linux/jq-command-json](https://www.baeldung.com/linux/jq-command-json)

```auto
$ curl -s localhost/api/config/dns/hosts | jq -r '.config.dns.hosts[] | select(.|test("router"))'
10.0.0.1 router.home.dehakkelaar.nl

```

```auto
$ curl -s localhost/api/config/dns/hosts | jq -r '.config.dns.hosts[] | select(.|test("10.0.0.3"))'
10.0.0.3 nas.home.dehakkelaar.nl

```

EDIT: Oh it might not be clear but I entered a blank Pi-hole password for easy tinkering:

`sudo pihole setpassword`

---

<div class="post-metadata">

**Author:** ![wzzrd](https://discourse-cdn.pi-hole.net/user_avatar/discourse.pi-hole.net/wzzrd/32/43701_2.png) [@wzzrd](https://discourse.pi-hole.net/u/wzzrd)\
**Post date:** [October 11, 2024, 6:43am UTC](https://discourse.pi-hole.net/t/scope-of-the-v6-api-includes-dns-cname-crud/73373/10 "2024-10-11T06:43:47Z")

</div>

That looks very interesting 😉

Thanks for all the information!
