This documentation covers Poweradmin 4.x. Some sections are still being expanded.

API Overview

Poweradmin exposes a REST API that mirrors what the web interface can do for zones, records, users, groups, permission templates, and zone templates. All the same validation, ownership checks, and SOA serial bumping run on every request, so anything you build on top of the API behaves the same as the UI.

For step-by-step setup, see the Headless / API-First Quickstart. For the full list of configuration options and security recommendations, see API Configuration.

Two API versions

Version Base path Status When to use
v2 /api/v2 Recommended All new integrations. Consistent response envelope, RRset endpoints, bulk record creation, zone owners, zone templates, groups.
v1 /api/v1 Legacy, still supported Existing integrations that have not migrated yet.

Both versions ship together. You can use v1 and v2 from the same client; the API keys and authentication are shared.

Response envelope

API v2 wraps every response in a consistent envelope:

{
  "success": true,
  "data": { ... }
}

On error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid record type",
    "details": { "field": "type", "value": "INVALID" }
  }
}

Paginated list endpoints add a pagination block alongside data.

What the API can do

  • Zones: list, create, update, delete; manage owners (v4.2.0+); list RRsets
  • Records: list per zone, create, update, delete, bulk create (v4.2.0+)
  • Users: full CRUD, list groups
  • Groups: full CRUD, manage members and zone assignments (v4.2.0+)
  • Permission templates: full CRUD
  • Zone templates: full CRUD, manage template records (v4.2.0+)
  • Permissions: list available permission flags

The complete endpoint list, request/response schemas, and an interactive explorer live at /api/docs on any instance with api.docs_enabled = true.

What still requires the web UI

A small number of operator workflows are not exposed through the API today:

  • Creating the first admin account (handled by the installer)
  • Issuing and rotating API keys (Settings -> API Keys)
  • Some global Poweradmin settings under Settings -> Configuration

If an endpoint you need is missing, please open an issue on the GitHub repository.

Companion projects

Two officially maintained projects already drive the Poweradmin API for you:

Next steps