Domains

Global Endpoints

List Domains

GET /v1/domains

Lists domains across all of the user's projects.

Auth: Required

Search Domains

GET /v1/domains/search?q=<query>

Searches for available domains via the Name.com API.

Auth: Required

Get Name Servers

POST /v1/domains/:domainName/name-server

Fetches current name servers for a domain from Name.com.

Auth: Required

Project-Scoped Endpoints

List Project Domains

GET /v1/projects/:projectId/domains

Returns domains with their DNS records.

Auth: Required (member, scope: domains:read)

Get Domain

GET /v1/projects/:projectId/domains/:domain

Returns a single domain with DNS records. For EXTERNAL domains, also returns verificationRecord — the DNS TXT record used to prove ownership (null once no longer needed).

Auth: Required (member, scope: domains:read)

Get Live DNS Records

GET /v1/projects/:projectId/domains/:domain/dns

Performs a live public DNS lookup for the domain and returns the resolved records (read-only). Intended for EXTERNAL domains, whose DNS is hosted outside Cosmoner and therefore has no stored records. Records are queried across the apex, common subdomains, and the _dmarc name — public DNS cannot enumerate a full zone, so only these names are returned.

Auth: Required (member, scope: domains:read)

Get Domain Price

GET /v1/projects/:projectId/domains/:domain/purchase

Checks availability and returns the purchase price from Name.com.

Auth: Required (member, scope: domains:read)

Register Domain (Checkout)

POST /v1/projects/:projectId/domains/:domain/checkout

Initiates a Stripe Checkout session to purchase a domain. Creates Stripe products/prices for the initial purchase and annual renewal.

Auth: Required (member, write access, scope: domains:write)

Migrate Domain

POST /v1/projects/:projectId/domains/:domain/migrate

Provisions a Cloudflare zone for a domain the user already owns. Returns NS records that must be set at the current registrar.

Auth: Required (member, write access, scope: domains:write)

Create Domain Record

POST /v1/projects/:projectId/domains

Creates a domain record (type: PURCHASED, MIGRATED, or EXTERNAL). EXTERNAL domains are ones you manage elsewhere — Cosmoner stores the record but you keep hosting the DNS at your own provider. An EXTERNAL domain must already exist in public DNS (a registered domain with nameservers); a name that doesn't resolve is rejected. They're created with status PENDING and must be verified (see below) before they become ACTIVE.

Auth: Required (member, write access, scope: domains:write)

Verify Domain Ownership

POST /v1/projects/:projectId/domains/:domain/verify

Checks public DNS for the TXT ownership record returned as verificationRecord on an EXTERNAL domain. Add a TXT record at your DNS provider with the given name and value, then call this endpoint to confirm it. On success the domain's status becomes ACTIVE; otherwise it stays PENDING and the response includes an error explaining why (DNS changes can take a while to propagate, so it's normal to retry a few times).

Domains added before the move to Cosmoner were issued a _datablock-challenge record instead. That older record is still accepted, so a pending domain that already published it verifies without changes — but verificationRecord always returns the current _cosmoner-challenge form for anything you add from now on.

Auth: Required (member, write access, scope: domains:write)

Delete Domain

DELETE /v1/projects/:projectId/domains/:domain

Removes a domain and its stored DNS records from the project. A domain that still has an email configuration or is in use by one or more apps cannot be deleted — remove those first.

Auth: Required (member, write access, scope: domains:write)