Add a delegated or purchased domain

POST

/v1/domains

• Production
• Local

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

• AgentKey
  domain:manage

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

Binds the domain to the connection’s project. Ordinary domains cannot be organization-wide.

string

default: project

Allowed values: 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

201

Connected; returns the nameserver records for delegated setup.

One of:

object

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

readiness

Authoritative domain outcome shared by the console, API, MCP and SDK. Show summary and next_action instead of interpreting verification_status, mode or dkim_status. ready_for_inboxes describes domain configuration only; creating an inbox still requires permission and available plan capacity. checked_at is the latest DNS observation, not an end-to-end mail test.

object

status

required

string

Allowed values: waiting_for_dns checking setting_up ready action_required needs_attention

label

required

string

summary

required

string

reason

required

string

action_required_by

required

string

Allowed values: customer extrovert none

next_action

required

string

Allowed values: check_dns_entries restore_dns wait create_inbox use_inbox ask_owner_to_create_inbox

ready_for_inboxes

required

boolean

checked_at

string format: date-time

next_check_at

string format: date-time

poll_after_seconds

required

integer

>= 1

inboxes

Omitted without inbox-read permission. Agent counts include only that agent’s visible inboxes.

object

scope

required

string

Allowed values: agent inbox selected_inboxes project organization

total

required

integer

ready

required

integer

setting_up

required

integer

needs_attention

required

integer

delegation

Customer nameserver health, independent of mail setup. Confirmed DNS is not mail readiness. Action required means restore the instructed nameservers; mail may be disrupted.

object

status

string

Allowed values: pending confirmed rechecking check_delayed action_required

checked_at

string format: date-time

confirmed_at

string format: date-time

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

object

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

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

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

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

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

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

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

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

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

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

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

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean