---
title: "Link a custom domain to a project, move it, or unlink it"
method: PATCH
path: "/account/domains/{domainId}"
---

# Link a custom domain to a project, move it, or unlink it

`PATCH /account/domains/{domainId}`

## Request

- Base URL: `https://api.eurobase.dev`
- URL: `https://api.eurobase.dev/account/domains/{domainId}`
- Auth: none declared

Workspace owner only. projectId names a project of the workspace, or null to unlink. DNS records and the certificate stay valid; an active domain serves the linked project production deployment at once, and serves nothing while unlinked.

## Path parameters

- `domainId` string, required

## Request body

- object
  - `projectId` string, nullable, required

## Response `200`

Domain linked, moved or unlinked

- ProjectDomainResponse
  - `domain` ProjectDomain, required
    - `id` string, required
    - `hostname` string, required
    - `status` 'pending' | 'issuing' | 'active' | 'failed', required
    - `statusReason` 'verification_timeout' | 'certificate_failed' | 'challenge_record_missing' | 'challenge_record_removed' | 'null', nullable, required
    - `records` object[], required: The records to add, each with what public DNS shows. A zone apex also lists its www companion (_acme-challenge.www and www), which redirects to the apex.
      - `type` 'CNAME' | 'A', required
      - `name` string, required: Fully qualified record name
      - `host` string, nullable, required: Record name relative to the domain DNS zone (@ for the zone itself); null until the zone is known
      - `value` string, nullable, required: Null only while custom domains are unavailable
      - `purpose` 'verification' | 'traffic', required
      - `state` 'ok' | 'waiting' | 'elsewhere', required: elsewhere: a traffic record that resolves to an address other than the edge
      - `observed` string[]
      - `aliasValue` string: For an A record: the hostname an ALIAS, ANAME or flattened CNAME may point to instead
      - `acceptedValue` string: For the www record of a zone apex: the apex, which the CNAME may point to instead
    - `zone` string, nullable, required: The DNS zone the domain lives in, once public DNS shows it
    - `dnsTargetState` 'unknown' | 'ok' | 'elsewhere' | 'missing', required
    - `certificateState` 'waiting' | 'issuing' | 'issued', required
    - `www` object, nullable, required: A zone apex only: its www companion, which redirects to the apex while the apex certificate covers it. requested: being added to the certificate; issued: covered; failing: covered but not renewing; failed: not covered within 24 hours, so it was removed and the apex renews alone.
      - `name` string, required
      - `certificateState` 'none' | 'requested' | 'issued' | 'failing' | 'failed', required
    - `converging` boolean, required: The domain will change state without anyone acting (pending or issuing)
    - `checkedAt` string, date-time, nullable, required
    - `activeAt` string, date-time, nullable, required
    - `createdAt` string, date-time, required

## Other responses

- `400`: projectId missing (project-domain-target-required) or invalid (project-domain-target-invalid)
- `403`: Only the workspace owner can manage its domains (workspace-domain-owner-required)
- `404`: Domain not found (project-domain-not-found)
- `409`: A project outside the workspace (project-domain-workspace-mismatch)
- `429`: Too many changes by this user this hour

---

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