canonical: https://jentic.com/apis/powerdns.local/powerdns

# PowerDNS Authoritative HTTP API

The PowerDNS Authoritative HTTP API provides programmatic control over PowerDNS authoritative nameserver instances. It exposes 36 endpoints for managing DNS zones (create, modify, delete, export, notify, rectify), individual DNS records via zone patching, DNSSEC cryptographic keys, TSIG keys for zone transfers, zone metadata, server configuration, cache management, and autoprimary relationships. The API is self-hosted and communicates via the X-API-Key header.

## For AI agents

Manage DNS zones, records, DNSSEC keys, and server configuration on self-hosted PowerDNS authoritative nameserver instances. Supports zone creation, record updates, AXFR triggers, and cache flushing.

## Scope

Does not handle domain registration, DNS hosting billing, or CDN configuration - use for authoritative DNS zone and record management on self-hosted PowerDNS instances only.

## Capabilities

- Create, modify, and delete DNS zones with full record set management via zone patching
- Manage DNSSEC cryptographic keys including generation, activation, and deletion per zone
- Configure TSIG keys for authenticated zone transfers between primary and secondary servers
- Flush server cache selectively by domain name to force record re-resolution
- Export zone data in AXFR-compatible format for backup or migration
- Trigger zone notifications to secondary servers and rectify zone data for DNSSEC consistency
- Search across all zones and records by name or content pattern

## Use cases

### DNS Zone and Record Management

Programmatically manage DNS zones and their record sets on PowerDNS authoritative servers. The API supports creating zones in Native, Master, or Slave mode, patching individual record sets (add, modify, delete), and exporting full zone data. Record changes are applied atomically per zone patch request, ensuring consistency. Supports all standard record types including A, AAAA, CNAME, MX, TXT, SRV, and NS.

Example prompt: Create a new zone 'example.com' in Native mode via POST `/servers/{server_id}/zones`, then patch it to add an A record pointing to 192.0.2.1

### DNSSEC Key Management

Manage DNSSEC cryptographic keys for zones to enable authenticated DNS responses. The API provides endpoints to list, create, activate, deactivate, and delete cryptographic keys per zone. Key rollovers can be automated by creating new keys, activating them, and deactivating old keys in sequence. Supports both KSK and ZSK key types with configurable algorithms.

Example prompt: List all cryptographic keys for zone 'example.com' via GET `/servers/{server_id}/zones/{zone_id}/cryptokeys` and identify which key is currently active

### DNS Infrastructure Automation

Automate DNS infrastructure operations including cache flushing, zone notifications, AXFR retrieval, and server configuration inspection. The API enables infrastructure-as-code workflows where DNS state is managed declaratively. Cache flush endpoints allow targeted invalidation after record changes, while notify triggers immediate propagation to secondary servers without waiting for SOA timers.

Example prompt: Flush the cache for 'example.com' using PUT `/servers/{server_id}/cache/flush`, then trigger a NOTIFY to secondaries via PUT `/servers/{server_id}/zones/{zone_id}/notify`

### AI Agent DNS Operations

Enable AI agents to manage DNS infrastructure through Jentic by discovering zone and record management operations via intent search. Agents can create zones, update records, manage DNSSEC keys, and monitor server state without memorizing the PowerDNS API structure. Jentic provides operation schemas with field requirements so agents construct valid zone patches on first attempt.

Example prompt: Search Jentic for 'add a DNS A record', load the PowerDNS zone patch schema, and execute to add an A record for 'www.example.com' pointing to a specified IP address

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/servers/{server_id}/zones` | List all zones on the server |
| POST | `/servers/{server_id}/zones` | Create a new DNS zone |
| PATCH | `/servers/{server_id}/zones/{zone_id}` | Update records in a zone (add/modify/delete) |
| GET | `/servers/{server_id}/zones/{zone_id}/cryptokeys` | List DNSSEC cryptographic keys for a zone |
| PUT | `/servers/{server_id}/cache/flush` | Flush the server cache for a domain |
| GET | `/servers/{server_id}/zones/{zone_id}/export` | Export zone data in AXFR format |
| PUT | `/servers/{server_id}/zones/{zone_id}/notify` | Trigger NOTIFY to secondary servers |
| GET | `/servers/{server_id}/search-data` | Search records across all zones |

## Key resources

- **Servers** — List and inspect PowerDNS server instances and their configuration
- **Zones** — Create, modify, delete, export, notify, and rectify DNS zones with record management
- **Cryptokeys** — Manage DNSSEC cryptographic keys per zone
- **TSIG Keys** — Create and manage TSIG keys for authenticated zone transfers
- **Metadata** — Read and write zone metadata entries
- **Autoprimaries** — Configure automatic primary server relationships

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 67 / 100
  - AI-Readiness & Agent Experience: 56 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/powerdns.local/powerdns/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the PowerDNS Authoritative HTTP API by hand means setting the X-API-Key header, pointing at your self-hosted `/api/v1` instance, and managing zone patch payloads yourself. Through Jentic you install once, import the PowerDNS Authoritative HTTP API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** PowerDNS puts the server and zone ids in the URL path (`/servers/{server_id}/zones/{zone_id}/...`), so a rule can pin your agent to one zone: it can read and patch records for that zone and nothing else. You choose the operations it may call, so a cache flush or a zone-wide notify is not included unless you add it.
- **Credential handling:** Your PowerDNS X-API-Key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a DNS zone' or 'export a zone file', and Jentic returns the matching PowerDNS operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cloudflare API** — Managed DNS with CDN, DDoS protection, and global anycast network
- **Linode API** — Cloud infrastructure with managed DNS service alongside compute and storage
- **DigitalOcean API** — Cloud infrastructure API including managed DNS alongside compute and networking

## FAQ

### What authentication does the PowerDNS Authoritative HTTP API use?

The PowerDNS API uses an API key passed in the X-API-Key HTTP header. This key is configured in the PowerDNS server's pdns.conf file via the api-key setting. Through Jentic, this key is stored encrypted in the credential vault and injected automatically into requests.

### Can I manage individual DNS records with the PowerDNS API?

Yes. Use PATCH `/servers/{server_id}/zones/{zone_id}` with a JSON body containing rrsets to add, modify, or delete individual record sets. Each rrset specifies the record name, type, TTL, and changetype (REPLACE or DELETE). Multiple record changes can be applied atomically in a single request.

### What are the rate limits for the PowerDNS Authoritative HTTP API?

The PowerDNS API is self-hosted, so rate limits depend on your server configuration and hardware capacity. There are no vendor-imposed external rate limits. Performance depends on zone count, record volume, and server resources allocated to the web API listener.

### How do I create a DNS zone through the PowerDNS API using Jentic?

Install the SDK with pip install jentic, then search for 'create a DNS zone'. Jentic returns the POST `/servers/{server_id}/zones` operation schema requiring name, kind (Native/Master/Slave), and nameservers array. Execute to create the zone, then use PATCH to add records.

### Does the PowerDNS API support DNSSEC key management?

Yes. The `/servers/{server_id}/zones/{zone_id}/cryptokeys` endpoints let you list, create, activate, deactivate, and delete DNSSEC keys. You can automate key rollovers by creating new keys with POST, activating them with PUT, and deleting old keys with DELETE. The rectify endpoint ensures zone data consistency after key changes.

### Can I limit what my agent is allowed to do with the PowerDNS Authoritative HTTP API?

Yes. Jentic One is self-hosted, so your own rules decide which PowerDNS operations and credentials the agent may use. Because PowerDNS puts the server and zone ids in the URL path, such as `/servers/{server_id}/zones/{zone_id}`, you can pin the agent to a single zone so it reads and patches records for that zone and nothing else. You also choose the operations it may call, so a cache flush or a zone-wide notify stays off limits unless you explicitly allow it.