Domains

Provision a complete agent identity in one call

Gives an AI agent a complete internet identity in a single request: buys the domain (if not already owned), sets up email DNS, creates a mailbox, and optionally registers an authenticated webhook for inbound email and domain events. webhook_headers accepts only Authorization and X-API-Key; values are encrypted at rest and never returned. Repeating the same domain, mailbox slug, and webhook URL reuses those resources.

Every webhook input is validated before a domain purchase or charge. The domain purchase is the only step that can charge and the only hard prerequisite - if it fails, the whole call fails (402 for payment, 409 if taken by another account). Email setup, mailbox creation, and webhook registration are best-effort: transient issues (e.g. DNS still propagating) are returned in warnings rather than failing the call, so the agent always gets its domain.

Payment works exactly like POST /api/domains/buy (card, marketplace balance, or USDC via the PAYMENT-SIGNATURE header / two-step flow).

post/api/agents/provision

Request

  • Base URL: https://domani.run
  • URL: https://domani.run/api/agents/provision
  • Auth: HTTP bearer

Headers

PAYMENT-SIGNATUREstring

Base64-encoded x402 payment payload (USDC on Base) to pay for the domain with USDC.

Request body

domainstring required

Domain to give the agent. Bought if not already owned.

slugstring

Mailbox local part (hi@domain). Default 'hi'.

namestring

Display name for outbound email.

webhook_urlstring uri

Optional HTTPS URL to receive inbound email + domain events.

webhook_eventsstring[]

Webhook event types. Defaults to email.received/delivered/bounced.

payment_method'card' | 'usdc' | 'balance'

How to pay for the domain.

payment_txstring

USDC tx hash (two-step flow).

payment_chain'base' | 'ethereum'
yearsinteger
max_pricenumber

Ceiling in USD for the domain charge. If the real price exceeds it, the request fails with 400 PRICE_ABOVE_MAX and nothing is charged. The error's price field is the total to accept; confirm it with the user before retrying with that max_price.

Example request

{
  "domain": "myagent.run",
  "slug": "hi",
  "max_price": 20
}

Response

Agent provisioned (domain already owned)

domainstring required
domain_status'registered' | 'owned' required
warningsstring[] required
hintstring required
next_stepsstring[] required

Changes

No recorded changes to this operation across all 2 revisions of this API.