Skip to content
Extrovert Extrovert Docs

Add a delegated or purchased domain

POST
/v1/domains

Add a domain the customer controls. ns_delegated is the default: the customer publishes the returned nameserver records and Extrovert serves the inbox domain’s mail zone. The legacy purchased intent creates a commerce request and cannot charge or register until human or pre-authorized policy approval; use /v1/commerce/requests/domain-purchases for its canonical response. ns_delegated needs domain:manage only. scope chooses the domain’s visibility (org shared by default, or project bound to the key’s project).

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Request body for the agent-facing POST /v1/domains. ns_delegated adds a domain the customer controls without spending. The legacy purchased input is accepted only as a compatibility shim and is converted to the human-controlled commerce request flow; it never approves, charges, or registers inline.

object
domain
required
string
mode

Onboarding path. Defaults to ns_delegated. purchased is a deprecated compatibility input that creates a commerce request.

string
Allowed values: ns_delegated purchased
scope

Domain visibility. Defaults to org (org-shared, usable by every project in the org). project binds the domain to the key’s OWN bound project (never client-selected) so it can create inboxes only in that project. A legacy/unscoped key (no bound project) falls back to org.

string
Allowed values: org project
project_id

Optional assertion that must match the key’s bound project; NEVER a selector. A mismatch is 403. The binding is always derived from the key.

string

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Connected; returns the nameserver records for delegated setup.

One of:

The agent-facing view of one domain: its status plus the nameserver records the customer must publish for delegated setup. Records are empty on list reads and for hosted/purchased modes.

object
id
string
domain
string
mode
string
Allowed values: shared ns_delegated manual purchased
verification_status
string
dkim_status
string
shared
boolean
provisioning_phase
string
provisioning_error
string
created_at
string format: date-time
records
Array<object>

A DNS record the customer must add for domain onboarding.

object
name
string
type
string
Example
TXT
value
string
priority
integer
nullable
ttl
integer
delegation_ns
Array<object>

A DNS record the customer must add for domain onboarding.

object
name
string
type
string
Example
TXT
value
string
priority
integer
nullable
ttl
integer
instruction
string

202

Section titled “202 ”

Legacy purchased intent recorded as a commerce request.

object
object
required
string
Allowed values: commerce_request
id
required
string
project_id
string
agent_id

Present when an agent initiated the request.

string
kind
required
string
Allowed values: domain_purchase plan_change
state
required
string
domain
string
domain_scope
string
Allowed values: org project
target_plan
string
current_plan
string
rationale
string
currency
required
string
quote_cents
required
integer format: int64
renewal_cents
required
integer format: int64
approved_max_cents
integer format: int64
quote_expires_at
string format: date-time
auto_renew
required
boolean
required_plan
string
required_plan_price_cents
integer format: int64
blocker_code
string
blockers
required
Array<object>
object
code
required
string
message
required
string
scope
string
limit_id
string
used_cents
integer format: int64
reserved_cents
integer format: int64
limit_cents
integer format: int64
requested_cents
integer format: int64
used_count
integer format: int64
reserved_count
integer format: int64
limit_count
integer format: int64
reset_at
string format: date-time
manage_url
string format: uri
approval_url
string format: uri
payment_action_url
string format: uri
external_job_id
string
effective_at
string format: date-time
agent_next_action
required
string
retry_safe
required
boolean
poll_after_seconds
required
integer
version
required
integer format: int64
notification_state
string
notification_last_error
string
created_at
required
string format: date-time
updated_at
required
string format: date-time

400

Section titled “400 ”

Invalid request.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope

401

Section titled “401 ”

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope

403

Section titled “403 ”

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope

409

Section titled “409 ”

Resource conflict (e.g. a duplicate entry).

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope

503

Section titled “503 ”

A required capability is not configured (e.g. buy-through-us).

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope