API reference

The complete dnswiz HTTP API. New to it? Start with the Quickstart, 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; the type 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.

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"

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/{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 monitored health-check target. `target` is the probe destination; `value` is the IP returned in DNS answers. List/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
`target`	`string`	yes
`value`	`string`	yes
`host`	`string`	yes
`port`	`integer`	yes
`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
`target`	`string`	yes
`value`	`string`	no
`host`	`string`	no
`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

GSLBPoolRef

Field	Type	Required
`pool_id`	`string <uuid>`	yes
`pool_name`	`string`	yes
`health_score`	`integer`	yes
`enabled_up`	`integer`	yes
`enabled_total`	`integer`	yes

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

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

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