---
title: "Add a domain"
method: POST
path: "/v1/dns-zones"
tags: ["public", "dns"]
---

# Add a domain

`POST /v1/dns-zones`

## Request

- Base URL: `https://api.vozora.io`
- URL: `https://api.vozora.io/v1/dns-zones`
- Auth: API key in header `Authorization`

Creates an unverified preparation. Nothing is published until ownership is proved.

## Headers

- `Idempotency-Key` string, required

## Response `201`

Created

- ZonesPublicZone
  - `alias_health` string
  - `applied_version` integer
  - `created_at` string
  - `delegation` string
  - `delegation_observed_at` string
  - `desired_version` integer: DesiredVersion is what the next If-Match must carry; AppliedVersion is what the estate has actually served. They differ while a change is in flight, which is what a poller watches.
  - `id` string
  - `lifecycle` string
  - `name` string
  - `preparation_expires_at` string: Named for what it is, not for the token: this is when an unverified preparation lapses, and calling it a "token deadline" both puzzles a customer and makes a timestamp look like a credential.
  - `publication` string
  - `recoverable_until` string
  - `status_url` string
  - `suspended` boolean
  - `updated_at` string
  - `verified_at` string

## Other responses

- `401`: invalid or missing API key
- `403`: the key lacks dns_zones:create
- `409`: zone_exists or name_unavailable
- `422`: validation_error, reserved_name or quota_exceeded

---

[API](https://skmtc.dev/vozora/apis/vozora-api.md) · [All operations](https://skmtc.dev/vozora/apis/vozora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vozora/apis/vozora-api/revisions/56f15734fc5a?raw)