---
title: "Update domain"
method: PATCH
path: "/v1/domains/{domain_id}"
tags: ["Domains"]
---

# Update domain

`PATCH /v1/domains/{domain_id}`

## Request

- Base URL: `https://api.winnr.app`
- URL: `https://api.winnr.app/v1/domains/{domain_id}`
- Auth: HTTP bearer

Update domain settings.

## Path parameters

- `domain_id` string, required

## Request body

- UpdateDomainRequest
  - `tags` string[]

## Response `200`

Updated domain

- DomainResponse
  - `data` Domain
    - `id` string: Firestore document ID for the domain.
    - `name` string: Domain name (e.g. "example.com").
    - `status` 'pending' | 'complete' | 'deleting': Current lifecycle state of the domain. - `pending` — provisioning in progress (registration, mailbox setup, DNS). - `complete` — provisioning finished and DNS records verified. - `deleting` — domain teardown in progress; will disappear from this list once the async deletion job finishes. Some legacy documents may still report `active`; treat it as equivalent to `complete`.
    - `dns_provider` string, nullable: Where the domain's DNS is hosted. One of `cloudflare`, `route53`, `clouddns1`, `clouddns2`, `clouddns3`, or null if not yet determined.
    - `dns_status` string, nullable: DNS provisioning state (did setup finish writing the zone/records). This does NOT reflect what public nameservers currently serve — check `dns_health` for the live view.
    - `dns_health` object, nullable: Live DNS health, refreshed by a daily check (and immediately after provisioning for connected domains). Reflects what the domain's public DNS actually serves, independent of `dns_status`. Absent until the first check runs.
      - `status` 'healthy' | 'degraded' | 'failing'
      - `issues` string[]: Present when not healthy; human-readable descriptions of each failing check, e.g. "Nameservers not pointing to cloudflare (current: ns1.dyna-ns.net, ns2.dyna-ns.net)".
      - `checked_at` string, date-time, nullable
    - `ns_status` string, nullable: Nameserver delegation status (matches Winnr's nameservers vs. third-party).
    - `registrar` string, nullable: Registrar name, e.g. `dynadot`. Null for BYOD domains.
    - `redirect_url` string, nullable: Apex redirect target, if a redirect is configured.
    - `forward_address` string, nullable: Catch-all forward address, if forwarding is configured.
    - `tags` string[]
    - `email_users_count` integer: Number of email users currently provisioned on this domain.
    - `expire_date` string, date-time, nullable: Domain registration expiration. Null for BYOD domains.
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
    - `payment_status` string, nullable: Present only for domains that go through Winnr's domain purchase flow. Typical values include `paid`, `pending`, `failed`.
    - `payment_method` string, nullable: Payment method used (only when `payment_status` is set).
    - `payment_amount` number, nullable: Amount charged in USD (only when `payment_status` is set).
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `401`: Authentication required or token invalid
- `404`: Resource not found

---

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