API reference

The complete dnswiz HTTP API. New to it? Start with theQuickstart, it walks the create-zone → add-record → verify thread end to end.

Example requests below assume $DNSWIZ_API_KEY is exported. Mint one in console → Settings → API keys.

Auth & conventions

Base URL. https://api.dnswiz.app in prod,http://localhost:8787 for local dev.
Auth. Bearer token in Authorization. Two kinds: session tokens from POST /v1/auth/verify and API keys minted at /v1/api-keys (prefix dnswiz_).
Errors. RFC 7807 problem+json; thetype URI links to an error doc.
Lists. Cursor pagination, envelope{ items, next_cursor }.
Mutations. Accept Idempotency-Key.

auth

POST/v1/auth/send

Send a magic-link sign-in email.

Request body

object

Responses

Status	Description	Schema
`200`	link sent (always 200, no enumeration leak)	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/auth/send

POST/v1/auth/verify

Verify a magic-link token and start a session.

If the email is new, a tenant is auto-created with the user as owner and a sample zone is seeded. If the email exists, a session is attached to the existing tenant.

Request body

object

Responses

Status	Description	Schema
`200`	session created	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/auth/verify

POST/v1/auth/logout

Revoke the current session.

Responses

Status	Description	Schema
`204`	revoked
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/auth/logout \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/auth/mfa/state

Whether the caller has TOTP MFA enrolled.

Responses

Status	Description	Schema
`200`	enrollment state	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/auth/mfa/state \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/auth/mfa/enroll/start

Begin TOTP enrollment; returns the otpauth URL and one-time recovery codes.

Responses

Status	Description	Schema
`200`	enrollment secret and recovery codes	`object`
`409`	already enrolled (disable first)
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/auth/mfa/enroll/start \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/auth/mfa/enroll/verify

Confirm the first TOTP code to activate enrollment.

Request body

MFACode

Responses

Status	Description	Schema
`200`	enrolled	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/auth/mfa/enroll/verify \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/auth/mfa/verify

Clear the MFA gate for the current session with a TOTP code.

Request body

MFACode

Responses

Status	Description	Schema
`200`	verified	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/auth/mfa/verify \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/auth/mfa/recovery

Clear the MFA gate using a recovery code instead of a TOTP code.

Request body

MFACode

Responses

Status	Description	Schema
`200`	verified	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/auth/mfa/recovery \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/auth/mfa

Disable MFA for the caller (requires a current TOTP code).

Request body

MFACode

Responses

Status	Description	Schema
`200`	disabled	`object`
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/auth/mfa \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/auth/restorable

List the caller's soft-deleted workspaces still inside the 30-day purge window.

Responses

Status	Description	Schema
`200`	restorable workspaces	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/auth/restorable \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/auth/restore/{tenant_id}

Undelete a soft-deleted workspace (owner or admin only).

Responses

Status	Description	Schema
`200`	restored	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/auth/restore/{tenant_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

me

GET/v1/me

Get the current user, tenant, plan, usage, and onboarding state.

Responses

Status	Description	Schema
`200`	profile	`Me`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/me \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/me/dashboard

Workspace cockpit, vital signs, top names/zones, certs, incidents.

Responses

Status	Description	Schema
`200`	dashboard payload	`Dashboard`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/me/dashboard \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/me/account

Update the current user's display name.

Request body

object

Responses

Status	Description	Schema
`204`	updated
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/me/account \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/me/export

Download every zone + record as a ZIP bundle.

Responses

Status	Description	Schema
`200`	zip archive
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/me/export \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/me/cert-config

Get the tenant's ACME/cert-issuance config (own overrides plus effective values).

Responses

Status	Description	Schema
`200`	cert config	`CertConfig`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/me/cert-config \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/me/cert-config

Override the tenant's ACME directory, account email, or EAB credentials.

Request body

CertConfig

Responses

Status	Description	Schema
`200`	updated cert config	`CertConfig`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/me/cert-config \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/me/cert-config

Revert the tenant to the platform default ACME config.

Responses

Status	Description	Schema
`200`	reverted cert config	`CertConfig`
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/me/cert-config \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/me/tenant

Update workspace settings (name, billing email, record/SOA/negative-TTL defaults).

Partial update. Empty string clears billing_email/default_soa_rname; a negative default_negative_ttl clears it.

Request body

object

Responses

Status	Description	Schema
`204`	updated
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/me/tenant \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/me/tenant

Soft-delete the workspace (30-day grace, then purged).

Requires sudo and a name-match confirmation in the body. The soft-delete cancels Stripe subscriptions immediately and starts the 30-day purge clock.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

object

Responses

Status	Description	Schema
`204`	deleted (soft)
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/me/tenant \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

plans

GET/v1/plans

List public pricing tiers.

Responses

Status	Description	Schema
`200`	plans	`Plan[]`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/plans

zones

GET/v1/zones

List zones.

Parameters

Name	In	Type	Required
`cursor`	query	`string`	no
`limit`	query	`integer`	no

Responses

Status	Description	Schema
`200`	page of zones	`ZonePage`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/zones \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/zones

Create a zone.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

ZoneCreate

Responses

Status	Description	Schema
`201`	created	`Zone`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/zones \
  -H "Authorization: Bearer $DNSWIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "example.com"
     }'

Example response

{
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "example.com.",
  "active": true,
  "created_at": "2026-05-28T09:00:00Z",
  "updated_at": "2026-05-28T09:00:00Z"
}

GET/v1/zones/{zone_id}

Get a zone.

Responses

Status	Description	Schema
`200`	zone	`Zone`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/zones/{zone_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

Example response

{
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "example.com.",
  "active": true,
  "created_at": "2026-05-28T09:00:00Z",
  "updated_at": "2026-05-28T09:00:00Z"
}

PATCH/v1/zones/{zone_id}

Update a zone (activation and SOA/TTL defaults).

Partial update; send at least one field. Clear sentinels: send a negative `default_ttl` or `negative_ttl` to clear it (inherit the default), and an empty `soa_rname` to clear it.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

ZoneUpdate

Responses

Status	Description	Schema
`200`	updated	`Zone`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/zones/{zone_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

Example response

{
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "example.com.",
  "active": true,
  "created_at": "2026-05-28T09:00:00Z",
  "updated_at": "2026-05-28T09:00:00Z"
}

DELETE/v1/zones/{zone_id}

Delete a zone.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Responses

Status	Description	Schema
`204`	deleted
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/zones/{zone_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/zones/{zone_id}/health

Zone health report (overall + per-category scores + individual checks).

Recomputed on every request; not persisted.

Responses

Status	Description	Schema
`200`	health report	`ZoneHealth`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/zones/{zone_id}/health \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/zones/{zone_id}/health/ack

Acknowledge (mute) a health check with a reason.

Request body

object

Responses

Status	Description	Schema
`204`	acknowledged
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/zones/{zone_id}/health/ack \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/zones/{zone_id}/health/ack/{check_id}

Clear a health-check acknowledgement.

Responses

Status	Description	Schema
`204`	cleared
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/zones/{zone_id}/health/ack/{check_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

records

GET/v1/zones/{zone_id}/records

List records in a zone.

Parameters

Name	In	Type	Required
`cursor`	query	`string`	no
`limit`	query	`integer`	no

Responses

Status	Description	Schema
`200`	page of records	`RecordPage`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/zones/{zone_id}/records

Create a record.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

RecordCreate

Responses

Status	Description	Schema
`201`	created	`Record`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer $DNSWIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "www",
       "type": "A",
       "ttl": 300,
       "data": {
         "value": "203.0.113.10"
       }
     }'

Example response

{
  "id": "11111111-0000-0000-0000-000000000000",
  "zone_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "www",
  "fqdn": "www.example.com.",
  "type": "A",
  "ttl": 300,
  "ttl_inherit": false,
  "data": {
    "value": "203.0.113.10"
  },
  "active": true,
  "created_at": "2026-05-28T09:01:00Z",
  "updated_at": "2026-05-28T09:01:00Z"
}

GET/v1/records/{record_id}

Get a record.

Responses

Status	Description	Schema
`200`	record	`Record`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/records/{record_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

Example response

{
  "id": "11111111-0000-0000-0000-000000000000",
  "zone_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "www",
  "fqdn": "www.example.com.",
  "type": "A",
  "ttl": 300,
  "ttl_inherit": false,
  "data": {
    "value": "203.0.113.10"
  },
  "active": true,
  "created_at": "2026-05-28T09:01:00Z",
  "updated_at": "2026-05-28T09:01:00Z"
}

PATCH/v1/records/{record_id}

Update a record.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

RecordUpdate

Responses

Status	Description	Schema
`200`	updated	`Record`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/records/{record_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

Example response

{
  "id": "11111111-0000-0000-0000-000000000000",
  "zone_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "www",
  "fqdn": "www.example.com.",
  "type": "A",
  "ttl": 300,
  "ttl_inherit": false,
  "data": {
    "value": "203.0.113.10"
  },
  "active": true,
  "created_at": "2026-05-28T09:01:00Z",
  "updated_at": "2026-05-28T09:01:00Z"
}

DELETE/v1/records/{record_id}

Delete a record.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Responses

Status	Description	Schema
`204`	deleted
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/records/{record_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/records/{record_id}/test

Live-dig, resolve the record from the dnswiz edge fleet and return raw answers.

Request body

object

Responses

Status	Description	Schema
`200`	dig result	`LiveDig`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/records/{record_id}/test \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/records/{record_id}/canary/abort

Snap a CANARY record back to its primary (set ramp to 0%).

Responses

Status	Description	Schema
`200`	aborted	`Record`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/records/{record_id}/canary/abort \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

Example response

{
  "id": "11111111-0000-0000-0000-000000000000",
  "zone_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "www",
  "fqdn": "www.example.com.",
  "type": "A",
  "ttl": 300,
  "ttl_inherit": false,
  "data": {
    "value": "203.0.113.10"
  },
  "active": true,
  "created_at": "2026-05-28T09:01:00Z",
  "updated_at": "2026-05-28T09:01:00Z"
}

POST/v1/records/{record_id}/canary/resume

Resume a paused CANARY record from its current percentage.

Responses

Status	Description	Schema
`200`	resumed	`Record`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/records/{record_id}/canary/resume \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

Example response

{
  "id": "11111111-0000-0000-0000-000000000000",
  "zone_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "www",
  "fqdn": "www.example.com.",
  "type": "A",
  "ttl": 300,
  "ttl_inherit": false,
  "data": {
    "value": "203.0.113.10"
  },
  "active": true,
  "created_at": "2026-05-28T09:01:00Z",
  "updated_at": "2026-05-28T09:01:00Z"
}

GET/v1/records/{record_id}/target-stats

Observed per-endpoint answer share for a GSLB record over a window.

Parameters

Name	In	Type	Required
`window`	query	`string`	no

Responses

Status	Description	Schema
`200`	target stats	`RecordTargetStats`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/records/{record_id}/target-stats \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/zones/{zone_id}/records/import

Import a BIND-style zonefile (preview, or commit the parsed records).

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

RecordImport

Responses

Status	Description	Schema
`200`	import preview or commit result	`RecordImportResult`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/zones/{zone_id}/records/import \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

pools

GET/v1/pools

List pools.

Parameters

Name	In	Type	Required
`cursor`	query	`string`	no
`limit`	query	`integer`	no

Responses

Status	Description	Schema
`200`	page of pools	`PoolPage`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/pools \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/pools

Create a pool.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

PoolCreate

Responses

Status	Description	Schema
`200`	created	`Pool`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/pools \
  -H "Authorization: Bearer $DNSWIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "api-us-east",
       "health_monitor_id": "9a000000-0000-0000-0000-000000000000",
       "selection_method": "active-passive"
     }'

GET/v1/pools/memberships

List every pool membership across the workspace (endpoint to pool, with weight).

Responses

Status	Description	Schema
`200`	memberships	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/pools/memberships \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/pools/gslb-services

List GSLB records (POOL/GEO/CANARY) and the pools they route to.

Paged: a workspace with a hundred services, each with its pools and members, is a large response on a short refresh, and the caller cannot bound what it has already been sent. Default order puts the services least able to answer first, so what is broken is on the first page.

Parameters

Name	In	Type	Required
`q`	query	`string`	no
`only`	query	`string (silent)`	no
`sort`	query	`string (health \| name)`	no
`limit`	query	`integer`	no
`offset`	query	`integer`	no

Responses

Status	Description	Schema
`200`	gslb services	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/pools/gslb-services \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/pools/gslb-services

Create a load-balanced name and everything under it in one transaction.

Serving one name from several addresses otherwise means creating a health check, an endpoint per address, a pool, a member per endpoint and a DNS record, in an order that is not guessable, each able to fail and leave the rest behind. This creates them together or not at all. Give either `answers` to build a new pool from, or `pool_ids` that already exist; both together is refused rather than guessed at.

Request body

GSLBServiceCreate

Responses

Status	Description	Schema
`200`	created	`GSLBServiceCreated`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/pools/gslb-services \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/pools/{id}

Get a pool (aggregate health and member counts; members are a sub-resource).

Responses

Status	Description	Schema
`200`	pool	`Pool`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/pools/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/pools/{id}

Update pool name, description, health monitor, or selection method.

Request body

PoolUpdate

Responses

Status	Description	Schema
`200`	updated	`Pool`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/pools/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/pools/{id}

Delete a pool. Fails (409) if any record still references it.

Responses

Status	Description	Schema
`204`	deleted
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/pools/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/pools/{id}/members

List a pool's members.

Responses

Status	Description	Schema
`200`	members	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/pools/{id}/members \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/pools/{id}/members

Attach an existing endpoint as a pool member (idempotent; re-adding updates weight).

Request body

object

Responses

Status	Description	Schema
`200`	attached	`PoolMember`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/pools/{id}/members \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/pools/{id}/members/inline

Create an endpoint and attach it as a member in one call.

Request body

PoolMemberInline

Responses

Status	Description	Schema
`200`	created and attached	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/pools/{id}/members/inline \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/pools/{id}/records

List the DNS records that reference this pool.

Responses

Status	Description	Schema
`200`	records	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/pools/{id}/records \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/pools/{id}/members/{member_id}

Update member weight or priority.

Request body

object

Responses

Status	Description	Schema
`200`	updated	`PoolMember`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/pools/{id}/members/{member_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/pools/{id}/members/{member_id}

Detach a member from a pool.

Responses

Status	Description	Schema
`204`	detached
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/pools/{id}/members/{member_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/pools/{id}/members/{member_id}/enabled

Flip member enabled (drain / un-drain without deleting).

Request body

object

Responses

Status	Description	Schema
`200`	updated	`PoolMember`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/pools/{id}/members/{member_id}/enabled \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

endpoints

GET/v1/endpoints

List health-checked endpoints.

Parameters

Name	In	Type	Required
`cursor`	query	`string`	no
`limit`	query	`integer`	no

Responses

Status	Description	Schema
`200`	page of endpoints	`EndpointPage`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/endpoints \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/endpoints

Create an endpoint.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

EndpointCreate

Responses

Status	Description	Schema
`201`	created	`Endpoint`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/endpoints \
  -H "Authorization: Bearer $DNSWIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "api-us-east-1",
       "kind": "https",
       "target": "https://api-us-east.example.com/healthz",
       "value": "203.0.113.10",
       "expected_status": 200
     }'

GET/v1/endpoints/{id}

Get an endpoint with current health + recent incidents.

Responses

Status	Description	Schema
`200`	endpoint	`Endpoint`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/endpoints/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/endpoints/{id}

Update an endpoint.

Request body

EndpointCreate

Responses

Status	Description	Schema
`200`	updated	`Endpoint`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/endpoints/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "api-us-east-1",
       "kind": "https",
       "target": "https://api-us-east.example.com/healthz",
       "value": "203.0.113.10",
       "expected_status": 200
     }'

DELETE/v1/endpoints/{id}

Delete an endpoint (also removes pool memberships).

Responses

Status	Description	Schema
`204`	deleted
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/endpoints/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/endpoints/{id}/detail

Endpoint detail with uptime buckets and incident history over a window.

Parameters

Name	In	Type	Required
`window`	query	`string (24h \| 7d \| 30d \| 90d)`	no

Responses

Status	Description	Schema
`200`	endpoint detail	`EndpointDetail`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/endpoints/{id}/detail \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

health-monitors

GET/v1/health-monitors

List reusable probe policies.

Responses

Status	Description	Schema
`200`	monitors	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/health-monitors \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/health-monitors

Create a named monitor (interval/timeout/thresholds/expected status).

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

HealthMonitorCreate

Responses

Status	Description	Schema
`201`	created	`HealthMonitor`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/health-monitors \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/health-monitors/{id}

Get a monitor.

Responses

Status	Description	Schema
`200`	monitor	`HealthMonitor`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/health-monitors/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/health-monitors/{id}

Update a monitor (changes propagate to every attached member on next probe tick).

Request body

HealthMonitorCreate

Responses

Status	Description	Schema
`200`	updated	`HealthMonitor`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/health-monitors/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/health-monitors/{id}

Delete a monitor. Members that referenced it fall back to defaults.

Responses

Status	Description	Schema
`204`	deleted
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/health-monitors/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/health-monitors/{id}/clone

Clone a monitor (including a preset) into a new editable monitor.

Request body

object

Responses

Status	Description	Schema
`201`	created	`HealthMonitor`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/health-monitors/{id}/clone \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

policies

GET/v1/me/policies

List tenant-default policies (apply across every zone unless overridden).

Responses

Status	Description	Schema
`200`	policies	`Policy[]`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/me/policies \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/me/policies/{kind}

Update a tenant-default policy (enable/disable, set config).

Request body

PolicyUpdate

Responses

Status	Description	Schema
`200`	updated	`Policy`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/me/policies/{kind} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/zones/{zone_id}/security

List per-zone policies (firewall, hijack monitor) with their effective config.

Responses

Status	Description	Schema
`200`	policies	`Policy[]`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/zones/{zone_id}/security \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/zones/{zone_id}/security/{kind}

Update a per-zone policy (overrides tenant default).

Request body

PolicyUpdate

Responses

Status	Description	Schema
`200`	updated	`Policy`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/zones/{zone_id}/security/{kind} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/zones/{zone_id}/security/hijack-probes

Recent hijack-probe results (every 5 min from 8 public resolvers).

Responses

Status	Description	Schema
`200`	probes	`HijackProbe[]`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/zones/{zone_id}/security/hijack-probes \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

certs

GET/v1/certs

List issued certificates (most recent 500; not paginated).

Responses

Status	Description	Schema
`200`	issued certificates	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/certs \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/certs/issue

Issue (or re-issue) a TLS cert via ACME DNS-01. Returns the signed cert + chain.

Two flows: send a `csr` (you keep the private key; the response omits key_pem) or send `names` (dnswiz generates the keypair and returns key_pem once). Supply exactly one. dnswiz solves the DNS-01 challenge against its own authoritative zones.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

CertIssueRequest

Responses

Status	Description	Schema
`200`	issued	`CertIssueResponse`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/certs/issue \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/certs/coverage

Names that resolve to a public IP but have no covering TLS cert (gap detector).

Responses

Status	Description	Schema
`200`	coverage	`CertCoverage`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/certs/coverage \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

firewall

GET/v1/me/firewall/refused

Live ring buffer of recent firewall refusals (in-memory, ~1h, ≤200/tenant).

Parameters

Name	In	Type	Required
`limit`	query	`integer`	no

Responses

Status	Description	Schema
`200`	refusals, newest first	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/me/firewall/refused \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

insights

GET/v1/zones/{zone_id}/insights

Query stats, top names, latency, and qtype/rcode/country breakdowns for a zone.

Parameters

Name	In	Type	Required
`window`	query	`string (1h \| 24h \| 7d \| 30d)`	no

Responses

Status	Description	Schema
`200`	insights payload	`Insights`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/zones/{zone_id}/insights \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/zones/{zone_id}/records/query-counts

Per-record query counts for a zone over a window (keyed by owner label).

Parameters

Name	In	Type	Required
`window`	query	`string (1h \| 24h \| 7d \| 30d)`	no

Responses

Status	Description	Schema
`200`	query counts	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/zones/{zone_id}/records/query-counts \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

notifications

GET/v1/notifications

List webhook notification channels.

Responses

Status	Description	Schema
`200`	channels	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/notifications \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/notifications

Create a webhook notification channel (returns the signing secret once).

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

NotificationChannelCreate

Responses

Status	Description	Schema
`201`	created	`NotificationChannel`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/notifications \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/notifications/log

List every notification raised for the workspace, subscribed to or not.

The history of what the platform noticed, independent of whether any channel was subscribed. Paged on the id of the oldest row returned: pass it back as `before` to continue. An offset would skip or repeat rows, because the log grows at the head while it is being read.

Parameters

Name	In	Type	Required
`event`	query	`string`	no
`before`	query	`integer <int64>`	no
`limit`	query	`integer`	no

Responses

Status	Description	Schema
`200`	notifications	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/notifications/log \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/notifications/{id}

Get a notification channel.

Responses

Status	Description	Schema
`200`	channel	`NotificationChannel`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/notifications/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/notifications/{id}

Update a notification channel.

Request body

NotificationChannelUpdate

Responses

Status	Description	Schema
`200`	updated	`NotificationChannel`
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/notifications/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/notifications/{id}

Delete a notification channel.

Responses

Status	Description	Schema
`204`	deleted
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/notifications/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/notifications/{id}/test

Send a synthetic test event to the channel.

Responses

Status	Description	Schema
`200`	queued	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/notifications/{id}/test \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

team

GET/v1/team/members

List workspace members.

Responses

Status	Description	Schema
`200`	members	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/team/members \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

PATCH/v1/team/members/{user_id}

Change a member's role (cannot target or set owner).

Request body

object

Responses

Status	Description	Schema
`204`	updated
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/team/members/{user_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/team/members/{user_id}

Remove a member from the workspace.

Responses

Status	Description	Schema
`204`	removed
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/team/members/{user_id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

GET/v1/team/invitations

List pending invitations.

Responses

Status	Description	Schema
`200`	invitations	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/team/invitations \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/team/invitations

Invite someone by email.

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

object

Responses

Status	Description	Schema
`201`	invited	`Invitation`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/team/invitations \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/team/invitations/accept

Accept an invitation by token; joins the workspace and returns a session scoped to it.

Request body

object

Responses

Status	Description	Schema
`200`	joined	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/team/invitations/accept \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/team/invitations/{id}

Revoke a pending invitation.

Responses

Status	Description	Schema
`204`	revoked
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/team/invitations/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

billing

GET/v1/me/billing

Current plan and subscription status.

Responses

Status	Description	Schema
`200`	billing summary	`object`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/me/billing \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/me/billing/checkout

Start a Stripe Checkout session for a plan upgrade.

Request body

object

Responses

Status	Description	Schema
`200`	redirect target	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/me/billing/checkout \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/me/billing/portal

Start a Stripe Customer Portal session.

Responses

Status	Description	Schema
`200`	redirect target	`object`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/me/billing/portal \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

api-keys

GET/v1/api-keys

List API keys (not paginated).

Responses

Status	Description	Schema
`200`	api keys	`ApiKey[]`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/api-keys \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/api-keys

Create an API key (returns the plaintext secret exactly once).

Parameters

Name	In	Type	Required
`Idempotency-Key`	header	`string`	no

Request body

ApiKeyCreate

Responses

Status	Description	Schema
`201`	created	`ApiKeyWithSecret`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/api-keys \
  -H "Authorization: Bearer $DNSWIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "ci-runner",
       "allowed_ips": []
     }'

PATCH/v1/api-keys/{id}

Update a key's source IP allow-list.

Request body

object

Responses

Status	Description	Schema
`204`	updated
`default`	Problem

Example request

curl -X PATCH https://api.dnswiz.app/v1/api-keys/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

DELETE/v1/api-keys/{id}

Delete an API key permanently.

Responses

Status	Description	Schema
`204`	deleted
`default`	Problem

Example request

curl -X DELETE https://api.dnswiz.app/v1/api-keys/{id} \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/api-keys/{id}/revoke

Revoke a key (idempotent; the key stops authenticating immediately).

Responses

Status	Description	Schema
`204`	revoked
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/api-keys/{id}/revoke \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

POST/v1/api-keys/{id}/regenerate

Roll a key's secret, returning the new plaintext exactly once.

Responses

Status	Description	Schema
`200`	regenerated	`ApiKeyWithSecret`
`default`	Problem

Example request

curl -X POST https://api.dnswiz.app/v1/api-keys/{id}/regenerate \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

audit

GET/v1/audit

List audit events.

Parameters

Name	In	Type	Required
`cursor`	query	`string`	no
`limit`	query	`integer`	no
`resource`	query	`string`	no
`action`	query	`string`	no

Responses

Status	Description	Schema
`200`	page of audit events	`AuditEventPage`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/audit \
  -H "Authorization: Bearer $DNSWIZ_API_KEY"

public

GET/v1/public/check

Free failover-readiness checker; pass a host, get a DNS + latency audit + score.

Parameters

Name	In	Type	Required
`host`	query	`string`	yes

Responses

Status	Description	Schema
`200`	audit result	`ReadinessCheck`
`default`	Problem

Example request

curl https://api.dnswiz.app/v1/public/check

system

GET/healthz

Liveness probe.

Responses

Status	Description	Schema
`200`	alive	`object`

Example request

curl https://api.dnswiz.app/healthz

GET/readyz

Readiness probe (DB reachable).

Responses

Status	Description	Schema
`200`	ready
`503`	not ready

Example request

curl https://api.dnswiz.app/readyz

Schemas

Object shapes referenced by the operations above.

ApiKey

Field	Type	Required
`id`	`string <uuid>`	yes
`name`	`string`	yes
`prefix`	`string`	yes
`scopes`	`string[]`	yes
`allowed_ips`	`string[]`	yes
`last_used_at`	`string <date-time>`	no
`expires_at`	`string <date-time>`	no
`revoked_at`	`string <date-time>`	no
`created_at`	`string <date-time>`	yes

ApiKeyCreate

Field	Type	Required
`name`	`string`	yes
`scopes`	`string[]`	no
`allowed_ips`	`string[]`	no
`expires_at`	`string <date-time>`	no

ApiKeyWithSecret

AuditEvent

Field	Type	Required
`id`	`integer <int64>`	yes
`user_id`	`string <uuid>`	no
`actor`	`string`	yes
`api_key_id`	`string <uuid>`	no
`api_key_name`	`string`	no
`ip`	`string`	no
`request_id`	`string`	no
`resource`	`string`	yes
`resource_id`	`string <uuid>`	no
`action`	`string`	yes
`before`	`object`	no
`after`	`object`	no
`occurred_at`	`string <date-time>`	yes

AuditEventPage

Field	Type	Required
`items`	`AuditEvent[]`	yes
`next_cursor`	`string`	yes

CertConfig

Per-tenant ACME override. The bare fields are the tenant's own overrides (empty when not set); the effective_* fields are what issuance actually uses (override, else platform default). The has_*/customized booleans and eab_hmac_b64/clear_eab_hmac are write-once or request-only knobs for the EAB secret.

Field	Type	Required
`directory_url`	`string`	no
`account_email`	`string`	no
`eab_kid`	`string`	no
`effective_directory_url`	`string`	no
`effective_account_email`	`string`	no
`effective_eab_kid`	`string`	no
`customized`	`boolean`	no
`has_own_account_key`	`boolean`	no
`has_eab_hmac`	`boolean`	no
`eab_hmac_b64`	`string`	no
`clear_eab_hmac`	`boolean`	no

CertCoverage

Field	Type	Required
`total_names`	`integer`	yes
`covered_names`	`integer`	yes
`gaps`	`CertCoverageGap[]`	yes

CertCoverageGap

Field	Type	Required
`name`	`string`	yes
`record_type`	`string`	yes
`zone_id`	`string <uuid>`	no
`zone_name`	`string`	no

CertIssuance

A successfully issued certificate. Rows exist only after issuance (there is no pending/failed state).

Field	Type	Required
`id`	`string <uuid>`	yes
`name`	`string`	yes
`san_names`	`string[]`	yes
`issuer`	`string`	yes
`serial`	`string`	yes
`issued_at`	`string <date-time>`	yes
`expires_at`	`string <date-time>`	yes
`days_to_expiry`	`integer`	yes

CertIssueRequest

Supply exactly one of csr or names.

Field	Type	Required
`csr`	`string`	no
`names`	`string[]`	no

CertIssueResponse

Field	Type	Required
`key_pem`	`string`	no
`cert_pem`	`string`	yes
`issuer_pem`	`string`	yes
`fullchain_pem`	`string`	yes
`serial`	`string`	yes
`expires_at`	`string <date-time>`	yes
`sans`	`string[]`	yes

DNSRow

Field	Type	Required
`value`	`string`	no
`ttl`	`integer`	no

Dashboard

Workspace cockpit payload. The response is wide and may gain fields over time; the stable, documented ones are below.

Field	Type	Required
`live_qps`	`number`	no
`queries_today`	`integer <int64>`	no
`queries_yesterday`	`integer <int64>`	no
`queries_month`	`integer <int64>`	no
`downtime_prevented_sec`	`integer <int64>`	no
`incidents_count_30d`	`integer`	no
`zones_healthy`	`integer`	no
`zones_total`	`integer`	no
`top_names_24h`	`object[]`	no
`countries_24h`	`object[]`	no
`certs`	`object`	no
`generated_at`	`string <date-time>`	no

Endpoint

A machine a pool can answer with. `address` is both what DNS returns and what the health check connects to. List and get responses also carry current `health` and 30-day `uptime`.

Field	Type	Required
`id`	`string <uuid>`	yes
`name`	`string`	yes
`kind`	`string (http \| https \| tcp)`	yes
`address`	`string`	yes
`probe_port`	`integer`	yes
`probe_host`	`string`	no
`expected_status`	`integer`	yes
`interval_seconds`	`integer`	yes
`timeout_seconds`	`integer`	yes
`healthy_after`	`integer`	yes
`unhealthy_after`	`integer`	yes
`health_monitor_id`	`string <uuid>`	no
`health`	`EndpointHealth`	no
`uptime`	`Uptime`	no
`created_at`	`string <date-time>`	yes
`updated_at`	`string <date-time>`	yes

EndpointCreate

Field	Type	Required
`name`	`string`	yes
`kind`	`string (http \| https \| tcp)`	yes
`address`	`string`	no
`probe_port`	`integer`	no
`expected_status`	`integer`	no
`interval_seconds`	`integer`	no
`timeout_seconds`	`integer`	no
`healthy_after`	`integer`	no
`unhealthy_after`	`integer`	no
`health_monitor_id`	`string <uuid>`	no

EndpointDetail

Field	Type	Required
`endpoint`	`Endpoint`	yes
`health`	`EndpointHealth`	yes
`window`	`string`	yes
`uptime`	`Uptime`	yes
`buckets`	`object[]`	yes
`incidents`	`object[]`	yes

EndpointHealth

Field	Type	Required
`endpoint_id`	`string <uuid>`	yes
`status`	`string (up \| down \| unknown)`	yes
`consecutive_passes`	`integer`	no
`consecutive_fails`	`integer`	no
`last_checked_at`	`string <date-time>`	no
`last_status_change_at`	`string <date-time>`	no
`last_latency_ms`	`integer`	no
`last_error`	`string`	no

EndpointPage

Field	Type	Required
`items`	`Endpoint[]`	yes
`next_cursor`	`string`	yes

FlatMembership

Field	Type	Required
`endpoint_id`	`string <uuid>`	yes
`pool_id`	`string <uuid>`	yes
`pool_name`	`string`	yes
`weight`	`integer`	yes

GSLBPoolMember

Field	Type	Required
`member_id`	`string <uuid>`	yes
`endpoint_id`	`string <uuid>`	yes
`name`	`string`	yes
`address`	`string`	no
`status`	`string (up \| down \| unknown)`	yes
`weight`	`integer`	yes
`priority`	`integer`	yes
`enabled`	`boolean`	yes
`latency_ms`	`integer`	no
`last_error`	`string`	no
`edges_up`	`integer`	no
`edges_total`	`integer`	no

GSLBPoolRef

Field	Type	Required
`pool_id`	`string <uuid>`	yes
`pool_name`	`string`	yes
`role`	`string`	no
`missing`	`boolean`	no
`selection_method`	`string (weighted \| active-passive \| round-robin)`	no
`health_score`	`integer`	yes
`enabled_up`	`integer`	yes
`enabled_total`	`integer`	yes
`members`	`GSLBPoolMember[]`	no

GSLBService

Field	Type	Required
`record_id`	`string <uuid>`	yes
`zone_id`	`string <uuid>`	yes
`zone_name`	`string`	yes
`name`	`string`	yes
`fqdn`	`string`	yes
`type`	`RecordType`	yes
`ttl`	`integer`	yes
`pools`	`GSLBPoolRef[]`	yes

GSLBServiceCreate

Field	Type	Required
`zone_id`	`string <uuid>`	yes
`name`	`string`	yes
`ttl`	`integer`	no
`selection_method`	`string (weighted \| active-passive \| round-robin)`	no
`answers`	`object[]`	no
`pool_ids`	`string <uuid>[]`	no
`check`	`object`	no

GSLBServiceCreated

Field	Type	Required
`record_id`	`string <uuid>`	yes
`pool_ids`	`string <uuid>[]`	yes
`endpoint_ids`	`string <uuid>[]`	yes
`monitor_id`	`string <uuid>`	no
`fqdn`	`string`	yes

GslbTarget

A GSLB destination used by GEO and CANARY records. Supply exactly one of: an endpoint (`endpoint_id` plus a `value` IP) or a pool (`pool_id`).

Field	Type	Required
`endpoint_id`	`string <uuid>`	no
`value`	`string`	no
`pool_id`	`string <uuid>`	no

HealthMonitor

A reusable probe policy (the "what": protocol, path, thresholds). The target host/port lives on the pool member that references it.

Field	Type	Required
`id`	`string <uuid>`	yes
`name`	`string`	yes
`is_preset`	`boolean`	yes
`kind`	`HealthMonitorKind`	yes
`path`	`string`	yes
`expected_status`	`integer`	yes
`interval_seconds`	`integer`	yes
`timeout_seconds`	`integer`	yes
`healthy_after`	`integer`	yes
`unhealthy_after`	`integer`	yes
`created_at`	`string <date-time>`	yes
`updated_at`	`string <date-time>`	yes

HealthMonitorCreate

Numeric fields left at zero take server defaults on create. On update, zero/empty leaves the field unchanged (so a field cannot be set to 0).

Field	Type	Required
`name`	`string`	yes
`kind`	`HealthMonitorKind`	yes
`path`	`string`	no
`expected_status`	`integer`	no
`interval_seconds`	`integer`	no
`timeout_seconds`	`integer`	no
`healthy_after`	`integer`	no
`unhealthy_after`	`integer`	no

HealthMonitorKind

Probe protocol. udp-dns and udp-ntp are the two UDP probes; there is no ICMP/ping probe.

HijackProbe

Field	Type	Required
`id`	`string <uuid>`	yes
`probed_at`	`string <date-time>`	yes
`resolver`	`string`	yes
`qname`	`string`	yes
`qtype`	`string`	yes
`expected`	`string`	no
`observed`	`string`	no
`diverged`	`boolean`	yes
`err`	`string`	no

Insights

Per-zone insights payload. Latency percentiles are in microseconds.

Field	Type	Required
`window_hours`	`integer`	yes
`total`	`integer <int64>`	yes
`previous_total`	`integer <int64>`	no
`time_series`	`object[]`	yes
`by_qtype`	`LabeledCount[]`	yes
`by_rcode`	`LabeledCount[]`	yes
`by_country`	`LabeledCount[]`	no
`top_names`	`LabeledCount[]`	yes
`latency`	`object`	yes
`recent`	`object[]`	no
`generated_at`	`string <date-time>`	yes

Invitation

Field	Type	Required
`id`	`string <uuid>`	yes
`tenant_id`	`string <uuid>`	yes
`email`	`string <email>`	yes
`role`	`string (admin \| editor \| viewer)`	yes
`invited_by`	`string <uuid>`	no
`expires_at`	`string <date-time>`	yes
`accepted_at`	`string <date-time>`	no
`revoked_at`	`string <date-time>`	no
`created_at`	`string <date-time>`	yes

LabeledCount

Field	Type	Required
`label`	`string`	yes
`count`	`integer <int64>`	yes

LiveDig

Result of resolving a record live from the dnswiz edge fleet.

Field	Type	Required
`question`	`object`	yes
`rcode`	`string`	yes
`answers`	`object[]`	yes
`duration_ms`	`integer <int64>`	yes
`picked_endpoint_id`	`string`	no
`picked_label`	`string`	no

MFACode

Field	Type	Required
`code`	`string`	yes

Me

Field	Type	Required
`user`	`object`	yes
`tenant`	`object`	yes
`role`	`string (owner \| admin \| editor \| viewer)`	yes
`plan`	`Plan`	yes
`usage`	`object`	yes
`onboarding`	`object`	yes
`nameservers`	`string[]`	yes

Member

Field	Type	Required
`user_id`	`string <uuid>`	yes
`email`	`string <email>`	yes
`name`	`string`	yes
`role`	`string (owner \| admin \| editor \| viewer)`	yes
`joined_at`	`string <date-time>`	yes

NotificationChannel

An outbound webhook channel. dnswiz POSTs signed events to `target` for the subscribed `events`.

Field	Type	Required
`id`	`string <uuid>`	yes
`name`	`string`	yes
`kind`	`string (webhook)`	yes
`target`	`string`	yes
`secret`	`string`	no
`events`	`string[]`	yes
`active`	`boolean`	yes
`created_at`	`string <date-time>`	yes
`updated_at`	`string <date-time>`	yes

NotificationChannelCreate

Field	Type	Required
`name`	`string`	yes
`kind`	`string (webhook)`	yes
`target`	`string`	yes
`events`	`string[]`	yes

NotificationChannelUpdate

Partial update; omitted fields are left unchanged.

Field	Type	Required
`name`	`string`	no
`target`	`string`	no
`events`	`string[]`	no
`active`	`boolean`	no

NotificationLogEntry

Field	Type	Required
`id`	`integer <int64>`	yes
`event`	`string`	yes
`severity`	`string (info \| warning \| critical)`	yes
`occurred_at`	`string <date-time>`	yes
`data`	`object`	yes
`channels_matched`	`integer`	yes
`channels_delivered`	`integer`	yes
`channels_failed`	`integer`	yes

Plan

Field	Type	Required
`id`	`string (free \| pro \| business \| enterprise)`	yes
`display_name`	`string`	yes
`monthly_price_cents`	`integer`	no
`yearly_price_cents`	`integer`	no
`max_zones`	`integer`	yes
`max_records_per_zone`	`integer`	yes
`included_monthly_queries`	`integer <int64>`	yes
`gslb_enabled`	`boolean`	yes
`sso_enabled`	`boolean`	yes
`audit_export_enabled`	`boolean`	yes
`byok_enabled`	`boolean`	yes
`is_enterprise`	`boolean`	yes

Policy

Field	Type	Required
`kind`	`string (hijack_monitor \| query_firewall)`	yes
`enabled`	`boolean`	yes
`config`	`object`	yes

PolicyUpdate

Field	Type	Required
`enabled`	`boolean`	no
`config`	`object`	no

Pool

A named group of endpoints with a selection method. The body carries aggregate health only; members are a separate sub-resource under /v1/pools/{id}/members.

Field	Type	Required
`id`	`string <uuid>`	yes
`name`	`string`	yes
`description`	`string`	no
`health_monitor_id`	`string <uuid>`	yes
`selection_method`	`SelectionMethod`	yes
`member_count`	`integer`	yes
`health_score`	`integer`	yes
`enabled_up`	`integer`	yes
`enabled_total`	`integer`	yes
`created_at`	`string <date-time>`	yes
`updated_at`	`string <date-time>`	yes

PoolCreate

Field	Type	Required
`name`	`string`	yes
`description`	`string`	no
`health_monitor_id`	`string <uuid>`	yes
`selection_method`		no

PoolMember

Field	Type	Required
`id`	`string <uuid>`	yes
`pool_id`	`string <uuid>`	yes
`endpoint_id`	`string <uuid>`	yes
`weight`	`integer`	yes
`priority`	`integer`	yes
`enabled`	`boolean`	yes
`created_at`	`string <date-time>`	yes

PoolMemberInline

Create an endpoint and attach it in one call. Prefer monitor_id (the member inherits the pool's monitor when omitted). The legacy check_url/expected_status/... fields are a fallback used only when monitor_id is empty.

Field	Type	Required
`label`	`string`	yes
`host`	`string`	yes
`port`	`integer`	no
`monitor_id`	`string <uuid>`	no
`weight`	`integer`	no
`enabled`	`boolean`	no
`value`	`string`	no
`check_url`	`string`	no
`expected_status`	`integer`	no
`interval_seconds`	`integer`	no
`timeout_seconds`	`integer`	no
`healthy_after`	`integer`	no
`unhealthy_after`	`integer`	no

PoolPage

Field	Type	Required
`items`	`Pool[]`	yes
`next_cursor`	`object`	no

PoolRecordRef

Field	Type	Required
`record_id`	`string <uuid>`	yes
`zone_id`	`string <uuid>`	yes
`zone_name`	`string`	yes
`name`	`string`	yes
`type`	`RecordType`	yes

PoolUpdate

Partial update; omitted fields are left unchanged.

Field	Type	Required
`name`	`string`	no
`description`	`string`	no
`health_monitor_id`	`string <uuid>`	no
`selection_method`	`SelectionMethod`	no

Problem

Field	Type	Required
`type`	`string <uri>`	yes
`title`	`string`	yes
`status`	`integer`	yes
`detail`	`string`	no
`instance`	`string`	no
`code`	`string`	no
`errors`	`object`	no

Rdata

Record data envelope. The concrete shape depends on the sibling `type` field; see the per-type Rdata* schemas below.

RdataANAME

ANAME (apex CNAME-flattening). `target` is the hostname to follow.

Field	Type	Required
`target`	`string`	yes

RdataAddress

A and AAAA. `value` is an IPv4 (A) or IPv6 (AAAA) literal.

Field	Type	Required
`value`	`string`	yes

RdataCAA

CAA. `value` is a single space-joined string "<flag> <tag> <value>"; flag 0-255, tag is issue | issuewild | iodef.

Field	Type	Required
`value`	`string`	yes

RdataCanary

CANARY. Ramps traffic from `primary` to `canary` over `ramp_seconds` starting at `started_at`. Set `aborted_at` plus `aborted_pct` to freeze the ramp at a percentage.

Field	Type	Required
`primary`	`GslbTarget`	yes
`canary`	`GslbTarget`	yes
`from_pct`	`integer`	no
`to_pct`	`integer`	no
`ramp_seconds`	`integer`	no
`started_at`	`string <date-time>`	no
`aborted_at`	`string <date-time>`	no
`aborted_pct`	`integer`	no

RdataGeo

GEO. Per-continent selection. Each region and the required `default` is a GslbTarget; region codes are unique.

Field	Type	Required
`regions`	`[]`	yes
`default`	`GslbTarget`	yes

RdataHostname

CNAME, NS, and PTR. `value` is a hostname; a trailing dot is added if omitted.

Field	Type	Required
`value`	`string`	yes

RdataMX

MX. A mail-exchanger host plus a preference number.

Field	Type	Required
`value`	`string`	yes
`priority`	`integer`	no

RdataPool

POOL. Points the name at a GSLB pool; the engine answers with a healthy member.

Field	Type	Required
`pool_id`	`string <uuid>`	yes

RdataSRV

SRV. `value` is a single space-joined string "<priority> <weight> <port> <target>".

Field	Type	Required
`value`	`string`	yes

RdataTXT

TXT. Free text, up to 4096 bytes, no NUL byte.

Field	Type	Required
`value`	`string`	yes

ReadinessCheck

Failover-readiness audit for a host (the public checker Report).

Field	Type	Required
`host`	`string`	yes
`resolvers`	`object[]`	yes
`records`	`object`	yes
`score`	`integer`	yes
`grade`	`string (A \| B \| C \| D \| F)`	yes
`findings`	`object[]`	yes
`generated_at`	`string <date-time>`	yes

Record

A DNS record. The `data` field is a typed rdata envelope whose shape is set by `type` (see the Rdata* schemas): address types carry `{value}`, MX/SRV/CAA/TXT carry a packed `value` string, ANAME carries `{target}`, and the GSLB types POOL/GEO/CANARY carry pool and endpoint references. `name` is "@" at the apex. `fqdn` is present on every record response except the canary abort/resume actions.

Field	Type	Required
`id`	`string <uuid>`	yes
`zone_id`	`string <uuid>`	yes
`name`	`string`	yes
`fqdn`	`string`	no
`type`	`RecordType`	yes
`ttl`	`integer`	yes
`ttl_inherit`	`boolean`	yes
`data`	`Rdata`	yes
`active`	`boolean`	yes
`comment`	`string`	no
`created_at`	`string <date-time>`	yes
`updated_at`	`string <date-time>`	yes

RecordCreate

`data` must match `type` (see Rdata). If `ttl` is omitted or <= 0, or `ttl_inherit` is true, the server resolves the effective TTL from the zone default, then the tenant default, then 300.

Field	Type	Required
`name`	`string`	yes
`type`	`RecordType`	yes
`ttl`	`integer`	no
`ttl_inherit`	`boolean`	no
`data`	`Rdata`	yes
`comment`	`string`	no

RecordImport

Field	Type	Required
`zonefile`	`string`	yes
`mode`	`string (preview \| commit)`	yes

RecordImportResult

Parse result. `rows` and `stats` describe the parsed zonefile (per-line outcome and aggregate counts); `inserted` is the number of records written (0 in preview mode).

Field	Type	Required
`inserted`	`integer`	yes
`stats`	`object`	no
`rows`	`object[]`	no

RecordPage

Field	Type	Required
`items`	`Record[]`	yes
`next_cursor`	`string`	yes

RecordTargetStats

Observed answer distribution across a GSLB record's endpoints.

Field	Type	Required
`window`	`string`	yes
`total`	`integer <int64>`	yes
`targets`	`object[]`	yes

RecordType

Standard DNS types plus dnswiz GSLB types. ANAME is apex CNAME-flattening; POOL points a name at a GSLB pool; GEO selects a target per continent; CANARY ramps traffic between two targets.

RecordUpdate

Partial update. `type` is immutable. Omitted fields are left unchanged; an empty `comment` clears it.

Field	Type	Required
`name`	`string`	no
`ttl`	`integer`	no
`ttl_inherit`	`boolean`	no
`data`	`Rdata`	no
`active`	`boolean`	no
`comment`	`string`	no

RefusedQuery

Field	Type	Required
`tenant_id`	`string <uuid>`	yes
`zone_id`	`string <uuid>`	yes
`qname`	`string`	no
`qtype`	`string`	yes
`source_ip`	`string`	no
`country`	`string`	no
`reason`	`string`	yes
`pii`	`string`	no
`checked_at_ms`	`integer <int64>`	yes

RestorableTenant

Field	Type	Required
`id`	`string <uuid>`	yes
`name`	`string`	yes
`slug`	`string`	yes
`deleted_at`	`string <date-time>`	yes
`purge_after`	`string <date-time>`	yes
`role`	`string (owner \| admin \| editor \| viewer)`	yes

SelectionMethod

GSLB routing algorithm. weighted picks a healthy member at random by weight; active-passive picks the lowest-priority healthy member (1 is primary); round-robin rotates fairly across healthy members.

Uptime

Field	Type	Required
`pct_30d`	`number`	no
`incident_count_30d`	`integer`	no
`last_incident_at`	`string <date-time>`	no
`current_down_since`	`string <date-time>`	no

Zone

A DNS zone. `default_ttl`, `soa_rname`, and `negative_ttl` are omitted when unset (the engine falls back to its defaults).

Field	Type	Required
`id`	`string <uuid>`	yes
`name`	`string`	yes
`active`	`boolean`	yes
`default_ttl`	`integer`	no
`soa_rname`	`string`	no
`negative_ttl`	`integer`	no
`created_at`	`string <date-time>`	yes
`updated_at`	`string <date-time>`	yes

ZoneCreate

Field	Type	Required
`name`	`string`	yes

ZoneHealth

Zone health report. Categories present only when they have checks.

Field	Type	Required
`overall`	`integer`	yes
`categories`	`object`	yes
`results`	`ZoneHealthCheck[]`	yes

ZoneHealthCheck

Field	Type	Required
`id`	`string`	yes
`category`	`string (security \| performance \| email)`	yes
`status`	`string (pass \| warn \| fail \| skip)`	yes
`summary`	`string`	yes
`detail`	`string`	yes
`auto_fixable`	`boolean`	yes
`ack`	`object`	no

ZonePage

Field	Type	Required
`items`	`Zone[]`	yes
`next_cursor`	`string`	yes

ZoneUpdate

Partial update; at least one field required. Use a negative `default_ttl`/`negative_ttl` or an empty `soa_rname` to clear that field and inherit the default.

Field	Type	Required
`active`	`boolean`	no
`default_ttl`	`integer`	no
`soa_rname`	`string`	no
`negative_ttl`	`integer`	no