---
title: Domains
description: Create a domain, prove control of it, and understand what verification fences before anything serves the name.
type: how-to
product: network
summary: A name a project controls, the record that proves it, and what deleting it does
updated: 2026-10-01
order: 0
---

<Callout tone="note" title="Today this runs on the management API">
Add a domain with `POST /v1/projects/{id}/domains`, attach hostnames under `/v1/projects/{id}/domains/{domain_id}/hostnames`, and check them with `…/hostnames/{hostname_id}/check`; the [Network quickstart](/docs/network/quickstart) walks through it. The `sylphx network domains` commands below are not served at api.sylphx.com.
</Callout>

A Domain is a name a project controls. It is verified once, before any
certificate or Route uses it, and nothing serves the name until it is. This page
takes a name from creation to a verified Domain, and says what deletion is
fenced by.

## Create the name

`spec.domain_name` is the fully qualified name, and it is the one field a
Domain needs. A wildcard is refused, so a Domain is always one exact name.

<PropertyTable
	properties={[
		{
			name: 'domain_name',
			type: 'string',
			required: true,
			description: 'The fully qualified name, for example example.com. Wildcards are refused.',
		},
		{
			name: 'verification_method',
			type: 'VerificationMethod',
			description: 'How control is proven; default TXT. One of txt, cname.',
		},
	]}
/>

```bash
sylphx network domains create \
  --parent orgs/acme/projects/shop \
  --spec.domain-name shop.example.com \
  --spec.verification-method txt
```

The id is the name with dots as dashes, so this Domain is `shop-example-com`
and its name is `orgs/acme/projects/shop/domains/shop-example-com`. The server
assigns an id when you leave it out, and the `dom_` id it reports is never
reused.

## Prove you control it

Verification is a DNS record you publish. Read the Domain back and
`status.verification` has it: `record_name` is the name to publish, for example
`_sylphx-verify.example.com`, `record_type` is `TXT` or `CNAME`, and
`record_value` is the value.

```bash
sylphx network domains get orgs/acme/projects/shop/domains/shop-example-com
```

The platform checks the record at a sweep, and `verify` checks it now instead:

```bash
sylphx network domains verify orgs/acme/projects/shop/domains/shop-example-com
```

`status.verified` says whether control was proven and `status.verify_time` is
when it was last proven. A Domain that is not verified reports it in
`status.conditions`: `Ready`, `Reconciling` or `Stalled`.

<Callout tone="warning" title="Verification is fail-closed">
Nothing that serves traffic uses an unverified name. A Route's host must be a
verified Domain or a subdomain of one, so an unproven name is not a slow name —
it is a name that cannot be pointed anywhere. [Routes](/docs/network/routes)
covers what a host may be.
</Callout>

## Update it

`verification_method` changes through `update` like any other spec field, which
is useful when a zone will not take the record you first asked for. The same
call takes `validate_only`, which runs every check and writes nothing, and
`allow_missing`, which creates the Domain when it does not exist — the
declarative upsert a pipeline wants.

```bash
sylphx network domains update orgs/acme/projects/shop/domains/shop-example-com \
  --spec.verification-method cname
```

Every change to `spec` increases the Domain's generation, and the status reports
the generation it was computed from, so a change that has not landed yet is
visible as an older `observed_generation`.

## Delete it

Deleting a Domain is `destructive`: the CLI asks before it runs, and the API
takes an `etag` that must match the Domain's current one. Delete with the etag
of the Domain you read, not of the one you remember.

```bash
sylphx network domains delete orgs/acme/projects/shop/domains/shop-example-com --yes
```

Two more fields soften a delete: `allow_missing` succeeds when the Domain is
already gone, and `validate_only` reports what would happen without happening.
A delete that the Domain's own state forbids fails with `INVALID_STATE` rather
than removing something in use.

<RelatedDocs
	links={[
		{
			href: '/docs/api/domains',
			label: 'The domains collection',
			description: 'Every method, its scope and its examples.',
		},
		{
			href: '/docs/network/quickstart',
			label: 'Quickstart',
			description: 'A name, its proof and its Route, in three calls.',
		},
		{
			href: '/docs/network/routes',
			label: 'Routes',
			description: 'What a Route may point at, and how overlap is refused.',
		},
	]}
/>