API Reference

Create a new account

Creates a new user account and returns an API key. Use this key as a Bearer token for all authenticated endpoints. Each account also receives a unique referral code. Pass a ref code to permanently link the new user to a referrer - the referrer earns a commission on all future domain purchases by this user.

{
  "api_key": "domani_sk_a1B2c3D4e5F6g7H8i9J0kLmN",
  "referral_code": "x7k9m2",
  "has_payment_method": false,
  "user": {
    "id": "cm5abc123",
    "email": "dev@example.com"
  }
}

curl -X POST https://domani.run/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

Send a magic link sign-in email

Sends a sign-in link to the provided email. If the user doesn't exist, creates an account first. The magic link redirects to the dashboard with auth credentials. For programmatic API access, use POST /api/auth/register to get an API key directly.

{
  "ok": true,
  "message": "Check your email for a sign-in link."
}

curl -X POST https://domani.run/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

Verify a magic link token

Validates the magic link token and redirects to the dashboard with auth credentials. Used by the magic link email - not typically called by agents directly. Agents should use POST /api/auth/register instead.

Get current account details

Returns the authenticated user's account information including email, payment status, contact info status, referral code, and usage counts. Agents should call this after authentication to check has_payment_method and has_contact before attempting purchases.

{
  "id": "cm5abc123",
  "email": "dev@example.com",
  "has_payment_method": true,
  "has_contact": true,
  "referral_code": "x7k9m2",
  "referral_rate": 20,
  "domain_count": 3,
  "token_count": 2,
  "created_at": "2025-01-15T10:30:00.000Z"
}

curl https://domani.run/api/me \
  -H "Authorization: Bearer domani_sk_xxx"

Update account preferences

Update the authenticated user's account preferences such as preferred payment method.

Delete account (blocked while domains are held)

Permanently delete the authenticated user's account, tokens, webhooks, mailboxes, and other application data. Registered domains are NOT deleted with the account: the request fails with 409 HAS_DOMAINS until every domain is transferred out. This action cannot be undone.

Get registrant contact info

Returns the authenticated user's WHOIS registrant contact information. Must be set before purchasing or transferring domains.

{
  "has_contact": true,
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "+1.2125551234",
    "email": "jane@example.com"
  }
}

curl https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx"

Set registrant contact info

Set or update your WHOIS registrant contact information. Required by ICANN before purchasing domains. Used as the domain registrant and billing contact. When updated, the new contact is automatically propagated to all active domains at registrars that support contact updates.

curl -X PUT https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","address1":"123 Main St","city":"New York","state":"NY","postal_code":"10001","country":"US","phone":"+1.2125551234","email":"jane@example.com"}'

Resend contact email verification

Resend the verification email for the account's contact email address. Rate limited to once per 15 minutes per email.

List all available TLDs with pricing

Returns all 1014+ available TLDs with registration, renewal, and transfer pricing. Supports filtering by price range, searching by TLD name, sorting, and pagination via limit/offset. When paginated, includes a Link header with the next page URL. Public endpoint - no authentication required. Authenticated requests get higher rate limits (60/min vs 30/min).

{
  "tlds": [
    {
      "tld": "xyz",
      "registration": 4.04,
      "renewal": 4.04,
      "transfer": 4.04
    },
    {
      "tld": "com",
      "registration": 10.88,
      "renewal": 13.08,
      "transfer": 13.08
    },
    {
      "tld": "dev",
      "registration": 15.85,
      "renewal": 15.85,
      "transfer": 15.85
    }
  ],
  "total": 1014,
  "offset": 0,
  "limit": null
}

curl https://domani.run/api/tlds?max_price=10&sort=price

Check availability and pricing for domains

Checks availability and pricing for one or more domains via RDAP + retail pricing. Use q for a single domain (returns flat object) or domains for multiple (returns array). Supports SSE streaming via Accept: text/event-stream header - closing the connection cancels all in-flight RDAP lookups server-side. Max 200 domains per request. Public endpoint - no authentication required. Authenticated requests get higher rate limits (60/min vs 20/min).

curl "https://domani.run/api/domains/search?q=mysite.com"

AI-powered domain suggestions with availability

Given a project description, generates full domain names with creative TLDs (e.g. codebuddy.dev, wavify.fm), checks availability, and returns only available domains with pricing. Uses an agentic loop that retries until enough available domains are found. Supports SSE streaming via Accept: text/event-stream - closing the connection cancels in-flight LLM generation and RDAP lookups server-side. Public endpoint - no authentication required.

{
  "suggestions": [
    {
      "domain": "codebuddy.dev",
      "price": 13,
      "currency": "USD"
    },
    {
      "domain": "aiforge.sh",
      "price": 33,
      "currency": "USD"
    },
    {
      "domain": "devcraft.app",
      "price": 13,
      "currency": "USD"
    }
  ],
  "checked": 42,
  "iterations": 2
}

curl "https://domani.run/api/domains/suggest?prompt=AI+coding+assistant"

Fast DNS-based domain existence check

Tests if a domain name is taken across many TLDs at once using DNS queries (faster than search, no pricing). Returns 'taken' (definitely registered) and 'candidates' (potentially available) arrays. Use this to narrow down before calling search for pricing. Public endpoint - no authentication required.

List all your registered domains

Returns all domains owned by the authenticated user, ordered by purchase date (newest first). Includes domain name, status, purchase date, and expiration date.

{
  "domains": [
    {
      "domain": "mysite.com",
      "status": "active",
      "purchasedAt": "2025-01-15T10:30:00.000Z",
      "expiresAt": "2026-01-15T10:30:00.000Z",
      "emailEnabled": true,
      "emailVerified": true,
      "emailVerifiedAt": "2025-01-15T10:35:00.000Z",
      "mailboxCount": 2
    },
    {
      "domain": "myapp.dev",
      "status": "active",
      "purchasedAt": "2025-02-01T14:00:00.000Z",
      "expiresAt": "2026-02-01T14:00:00.000Z",
      "emailEnabled": false,
      "emailVerified": false,
      "emailVerifiedAt": null,
      "mailboxCount": 0
    }
  ]
}

curl https://domani.run/api/domains \
  -H "Authorization: Bearer domani_sk_xxx"

Claim a free agent identity (<handle>.domani.run)

Gives an agent a free identity at <slug>.domani.run - a live profile page, no domain purchase, instantly. The frictionless way to start; upgrade to a real owned domain later. Requires account:write.

{
  "success": true,
  "id": "agent_abc123",
  "slug": "myagent",
  "url": "https://myagent.domani.run",
  "page_url": "https://domani.run/agents/myagent",
  "name": "My Agent",
  "bio": "I broker domains.",
  "emoji": "🤖",
  "email": null,
  "links": [],
  "views": 0,
  "created_at": "2026-07-11T00:00:00.000Z"
}

curl -X POST https://domani.run/api/agents/identity \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"slug": "myagent", "name": "My Agent", "bio": "I broker domains.", "emoji": "🤖"}'

List your agent identities

Lists the free identities (<handle>.domani.run) you've claimed. Requires account:read.

Update an agent identity

Update a free identity's name/bio/emoji/email/links. Requires account:write.

Release an agent identity

Releases a free identity handle so it's available again. Requires account:write.

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 a webhook for inbound email and domain events. 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).

curl -X POST https://domani.run/api/agents/provision \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "myagent.run", "slug": "hi", "webhook_url": "https://my-agent.example.com/inbox"}'

Purchase one or more domains

Purchases one or more domains and registers them immediately. Send {"domain": "..."} for single or {"domains": ["...", "..."]} for bulk (max 10). If the domain is listed for sale on the Domani marketplace, this endpoint automatically routes to a marketplace purchase instead of a fresh registration. The response includes years: 0 and marketplace_purchase: true to distinguish it from a registration. Marketplace purchases are single-domain only. The buyer pays the full listed price; the seller receives the price minus a platform commission (default 10%). Bulk purchases process each domain independently - failures don't block other purchases. The response includes results (succeeded), errors (failed), and summary with counts. Accepts three payment methods: 1. Card (default): Requires a card on file via POST /api/billing/setup. Charged per domain. 2. USDC (two-step): First call without payment to get a 402 with payment_options.crypto (wallet address, amount, chains). Send USDC on-chain, then retry with payment_tx and payment_chain in the request body. 3. x402 USDC (atomic): Include a PAYMENT-SIGNATURE header with a signed USDC payment on Base. Bulk purchases require a card on file (USDC not supported for multi-domain). If no payment is provided for single domain, returns HTTP 402 with payment instructions.

curl -X POST https://domani.run/api/domains/buy \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mysite.com"}'

Get detailed information about a domain you own

Returns comprehensive information about a domain: status, purchase date, expiry, payment method, security lock, WHOIS privacy, auto-renew status, and registration dates. The registrar object may be null if extended data is unavailable.

{
  "domain": "mysite.com",
  "status": "active",
  "auto_renew": true,
  "purchased_at": "2025-06-01T12:00:00.000Z",
  "expires_at": "2026-06-01T12:00:00.000Z",
  "days_until_expiry": 365,
  "payment_method": "card",
  "registrar_status": "connected",
  "registrar_checked_at": "2025-06-01T12:00:00.000Z",
  "registrar": {
    "security_lock": true,
    "whois_privacy": true,
    "auto_renew": true,
    "create_date": "2025-06-01T12:00:00Z",
    "expire_date": "2026-06-01T12:00:00Z"
  }
}

curl https://domani.run/api/domains/mysite.com \
  -H "Authorization: Bearer domani_sk_xxx"

Update domain settings

Update settings for a domain you own. Supports auto_renew, whois_privacy, and security_lock. At least one field must be provided.

curl -X PUT https://domani.run/api/domains/mysite.com/settings \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew": false}'

Update parking settings

Update parking and listing settings for a domain you own. Enable/disable the parking page and set a 'For Sale' listing price. When parking is enabled, visitors to the domain see a branded page. When a listing price is set, visitors see a 'For Sale' page with a contact form.

Forward a domain to a URL

Forward a domain you own to another URL (e.g. brand.com -> https://brand.dev) - useful for multi-TLD brands. The domain must point at domani's nameservers/parking IP for the redirect to serve. Permanent (308) by default or temporary (307). Requires domains:write scope.

Stop forwarding a domain

Remove a domain's redirect so it reverts to the parking page. Requires domains:write scope.

List a domain for sale

List a domain you own for sale on the Domani marketplace. Buyers can purchase it directly via the API. The domain must be active and not already listed. Fees: Domani charges a platform commission (default 10%) on successful sales. The seller receives the listed price minus the commission. The buyer pays the full listed price. Requires domains:write scope.

{
  "listing": {
    "id": "lst_abc123",
    "domain": "example.com",
    "price": 5000,
    "currency": "USD",
    "description": null,
    "status": "active",
    "created_at": "2026-03-14T12:00:00.000Z"
  },
  "hint": "example.com listed for sale at $5,000. Buyers can purchase it on the marketplace."
}

Update a domain listing

Update the price and/or description of an active marketplace listing. At least one field must be provided. Requires domains:write scope.

{
  "listing": {
    "id": "lst_abc123",
    "domain": "example.com",
    "price": 7000,
    "currency": "USD",
    "description": "Premium domain",
    "status": "active",
    "created_at": "2026-03-14T12:00:00.000Z"
  },
  "hint": "Listing for example.com has been updated. New price: $7,000."
}

Cancel a domain listing

Remove an active for-sale listing for a domain you own. The domain remains in your account but is no longer available for purchase on the marketplace. Requires domains:write scope.

{
  "domain": "example.com",
  "status": "cancelled",
  "hint": "Listing for example.com has been cancelled."
}

Get parking analytics

Get visitor analytics for a parked domain - page views, inquiries, conversion rate, 30-day daily breakdown, and recent inquiries.

{
  "domain": "example.com",
  "views_7d": 42,
  "views_30d": 156,
  "inquiries_30d": 3,
  "conversion_rate": 1.92,
  "daily_views": [
    {
      "date": "2026-02-25",
      "views": 7
    }
  ],
  "recent_inquiries": [
    {
      "email": "buyer@example.com",
      "offer": 500,
      "date": "2026-02-25T10:00:00Z"
    }
  ],
  "hint": "example.com received 156 views and 3 inquiries in the last 30 days (1.92% conversion)."
}

Get EPP auth code

Get the EPP/auth code needed to transfer a domain to another registrar. Automatically unlocks the domain if it's locked.

Get outbound transfer status

Check the status of an outbound domain transfer. Use after getting an auth code and initiating the transfer at the new registrar.

Check inbound transfer status

Check the status of an inbound domain transfer. Returns detailed status with actionable hints. Use after initiating a transfer with POST /api/domains/transfer.

Import an external domain

Import a domain you own at another registrar (GoDaddy, Namecheap, Cloudflare, etc.) to manage through domani.run. Free, no transfer needed. Returns a TXT record for DNS-based ownership verification.

Verify and complete domain import

Verify DNS TXT record and complete domain import. Call after adding the TXT record returned by POST /api/domains/import. Uses Cloudflare DNS-over-HTTPS to check propagation.

Plan how to adopt an existing domain

Read-only inspection of an existing domain before connecting or transferring it. Returns the current registrar, authoritative nameservers, DNS provider, DNSSEC state, account state, transfer price, safety invariants, and exact next API actions. Call this before requesting an EPP code. Connecting leaves registrar and DNS unchanged. Transferring preserves nameservers and does not migrate DNS.

Pre-check transfer eligibility

Check whether a domain is eligible for transfer before initiating. Returns transfer price, eligibility status, and any blockers (unsupported TLD, ICANN waiting period, domain locked). Call this before POST /api/domains/transfer.

Watch a domain for transfer eligibility

Watch a domain and get notified (email + transfer.eligible webhook) when it becomes eligible for transfer. Uses RDAP to check EPP status codes and ICANN 60-day lock windows. If already eligible, returns immediately without creating a watch.

Transfer domain from another provider

Initiate a domain transfer-in after planDomainAdoption and explicit price confirmation. Requires the authorization/EPP code from the current provider. The existing authoritative nameservers are preserved and verified. DNS migration is never implicit. Transfer typically takes 1-5 days to complete. Payment is charged upfront via card or USDC.

curl -X POST https://domani.run/api/domains/transfer \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mysite.com", "auth_code": "EPP-AUTH-CODE"}'

Renew a domain

Renew a domain you own for additional years (1-10). Payment is charged upfront. The new expiry date is returned in the response.

curl -X POST https://domani.run/api/domains/mysite.com/renew \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"years": 1}'

Buy an aftermarket domain

Buy a taken domain that's listed for sale on an aftermarket (Afternic / Sedo) at its buy-now price, through Domani. The listing price is re-checked live before charging; pass max_price to cap what you'll pay. Make-offer-only listings can't be bought here - use the broker (POST /api/broker) to negotiate a price instead. Payment works like a registration: card, USDC on Base (x402), or marketplace balance. Requires the domains:transfer scope. On success the domain lands in your account (status: active, or provisioning while a staged transfer finalizes).

curl -X POST https://domani.run/api/domains/coolname.com/buy-aftermarket \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Get DNS records for a domain you own

Returns all DNS records configured for a domain you own (A, AAAA, CNAME, MX, TXT, NS, ...), each with a stable id, plus a zone_version token (also sent as the ETag header). Pass zone_version back on PUT to detect concurrent zone changes.

{
  "domain": "mysite.com",
  "records": [
    {
      "id": "rec_1a2b3c4d5e6f",
      "type": "A",
      "name": "@",
      "value": "76.76.21.21",
      "ttl": 3600
    },
    {
      "id": "rec_2b3c4d5e6f7a",
      "type": "CNAME",
      "name": "www",
      "value": "mysite.com",
      "ttl": 3600
    },
    {
      "id": "rec_3c4d5e6f7a8b",
      "type": "MX",
      "name": "@",
      "value": "mail.example.com",
      "ttl": 3600,
      "priority": 10
    }
  ],
  "zone_version": "zv_9f8e7d6c5b4a3f2e"
}

curl https://domani.run/api/domains/mysite.com/dns \
  -H "Authorization: Bearer domani_sk_xxx"

Set DNS records for a domain you own

Upserts DNS records at the rrset level: for each (type, name) present in the payload, existing records at that (type, name) are replaced by the ones you send; rrsets NOT mentioned in the payload are preserved, and NS records are never touched. An automatic server-side backup of the zone is taken before every write. Concurrency: pass the zone_version from a prior GET (body field or If-Match header). If the zone changed since, the write fails with 409 DNS_VERSION_CONFLICT and returns the current records + version so you can re-merge and retry.

{
  "success": true,
  "domain": "mysite.com",
  "records": [
    {
      "type": "A",
      "name": "@",
      "value": "76.76.21.21",
      "ttl": 3600
    },
    {
      "type": "CNAME",
      "name": "www",
      "value": "cname.vercel-dns.com",
      "ttl": 3600
    }
  ]
}

curl -X PUT https://domani.run/api/domains/mysite.com/dns \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"records": [
    {"type": "A", "name": "@", "value": "76.76.21.21", "ttl": 3600},
    {"type": "CNAME", "name": "www", "value": "cname.vercel-dns.com", "ttl": 3600}
  ]}'

List DNSSEC DS records for a domain you own

Returns the DNSSEC delegation-signer (DS) records published at the registry for a domain you own, and whether DNSSEC is enabled. Pairs with TLSA records (set via the DNS endpoint) for DANE.

{
  "domain": "mysite.com",
  "enabled": true,
  "records": [
    {
      "keyTag": "12345",
      "algorithm": "13",
      "digestType": "2",
      "digest": "A1B2C3..."
    }
  ]
}

curl https://domani.run/api/domains/mysite.com/dnssec \
  -H "Authorization: Bearer domani_sk_xxx"

Publish a DNSSEC DS record (enable DNSSEC)

Publishes a delegation-signer (DS) record at the registry, enabling DNSSEC for the domain. Get the DS values from your DNS/zone provider after signing the zone.

curl -X POST https://domani.run/api/domains/mysite.com/dnssec \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"keyTag": "12345", "algorithm": "13", "digestType": "2", "digest": "A1B2C3..."}'

Remove a DNSSEC DS record (disable DNSSEC)

Removes a delegation-signer (DS) record at the registry by its key tag. Removing all DS records disables DNSSEC for the domain.

curl -X DELETE "https://domani.run/api/domains/mysite.com/dnssec?keyTag=12345" \
  -H "Authorization: Bearer domani_sk_xxx"

Capture a DNS snapshot

Captures all DNS records for a domain via public DNS lookups (Cloudflare DoH). Discovers subdomains from Certificate Transparency logs, SPF records, and common names. The snapshot is also stored server-side as a backup.

{
  "domain": "mysite.com",
  "records": [
    {
      "type": "A",
      "name": "@",
      "value": "76.76.21.21",
      "ttl": 3600
    },
    {
      "type": "CNAME",
      "name": "www",
      "value": "mysite.com",
      "ttl": 3600
    },
    {
      "type": "MX",
      "name": "@",
      "value": "aspmx.l.google.com",
      "ttl": 3600,
      "priority": 1
    }
  ],
  "subdomains": [
    "www",
    "mail",
    "api"
  ],
  "sources": [
    "ct",
    "wordlist"
  ],
  "capturedAt": "2026-03-06T12:00:00.000Z"
}

curl -X POST https://domani.run/api/domains/mysite.com/dns/snapshot \
  -H "Authorization: Bearer domani_sk_xxx"

Restore DNS from a snapshot

Applies DNS records from a snapshot to the domain's current registrar. Uses a diff algorithm to avoid duplicating records that already exist. If no snapshot is provided in the body, restores from the server-side backup (created by snapshot or transfer).

{
  "domain": "mysite.com",
  "applied": 5,
  "skipped": 2,
  "recordCount": 7,
  "errors": []
}

curl -X POST https://domani.run/api/domains/mysite.com/dns/restore \
  -H "Authorization: Bearer domani_sk_xxx"

Clone another domain's DNS onto this one

Copies the DNS setup of a source domain you own onto this domain - useful for multi-TLD brands (brand.com → brand.dev) that share the same A/CNAME/MX. Merges by default (source records win on any type+name collision, this domain's other records are kept); set replace: true for an exact mirror.

curl -X POST https://domani.run/api/domains/brand.dev/dns/clone \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"from": "brand.com"}'

Get nameservers for a domain

Returns the authoritative nameservers configured for a domain you own. If empty, DNS operations (parking, email, connect) will fail until nameservers are assigned.

{
  "domain": "mysite.com",
  "nameservers": [
    "ns1.systemdns.com",
    "ns2.systemdns.com",
    "ns3.systemdns.com"
  ],
  "default_nameservers": [
    "ns1.systemdns.com",
    "ns2.systemdns.com",
    "ns3.systemdns.com"
  ],
  "hint": "3 nameservers configured for mysite.com."
}

curl https://domani.run/api/domains/mysite.com/nameservers \
  -H "Authorization: Bearer domani_sk_xxx"

Set nameservers for a domain

Replace the nameservers for a domain you own. Requires 2–13 valid hostnames. Common values: OpenSRS DNS (ns1.systemdns.com, ns2.systemdns.com, ns3.systemdns.com).

{
  "success": true,
  "domain": "mysite.com",
  "nameservers": [
    "ns1.systemdns.com",
    "ns2.systemdns.com",
    "ns3.systemdns.com"
  ],
  "hint": "Nameservers for mysite.com updated to ns1.systemdns.com, ns2.systemdns.com, ns3.systemdns.com. Changes may take up to 48 hours to propagate."
}

curl -X PUT https://domani.run/api/domains/mysite.com/nameservers \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"nameservers": ["ns1.systemdns.com", "ns2.systemdns.com", "ns3.systemdns.com"]}'

Connect a domain to a hosting or email provider

Connects a domain to a hosting or email provider by auto-detecting the provider from a target URL or accepting an explicit provider name. For domains managed through the platform, DNS records are set automatically (status: dns_set). For imported domains (external registrar), returns the records as instructions to add manually at your registrar (status: manual_setup_required, records have status pending). Supported hosting providers: vercel, netlify, cloudflare-pages, github-pages, railway, fly. Supported email providers: google-workspace, fastmail, proton. Use GET /api/domains/{domain}/connect to list all available providers and methods.

curl -X POST https://domani.run/api/domains/mysite.com/connect \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"target": "my-app.vercel.app"}'

List available providers for connecting a domain

Returns all supported hosting and email providers with their connection methods. Use this to discover what providers are available before calling POST.

Verify that a provider connection is working

Runs the provider's verification check to confirm DNS records have propagated and the connection is active. Use after POST /api/domains/{domain}/connect to verify.

curl -X POST https://domani.run/api/domains/mysite.com/verify \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"target": "my-app.vercel.app"}'

Check domain health: DNS, SSL, email, expiry

Checks the health of a domain via DNS-over-HTTPS: A/AAAA/CNAME/MX/TXT/NS records, SSL certificate status, email configuration, and expiry date. Supports SSE streaming via Accept: text/event-stream - closing the connection cancels in-flight DNS/SSL checks server-side. Use this after connecting to verify DNS propagation.

{
  "domain": "mysite.com",
  "status": "active",
  "expires": "2027-02-18T00:00:00.000Z",
  "days_until_expiry": 365,
  "dns": {
    "propagated": true,
    "a": [
      "76.76.21.21"
    ],
    "aaaa": [],
    "cname": [],
    "mx": [],
    "txt": [],
    "ns": [
      "ns1.porkbun.com",
      "ns2.porkbun.com"
    ],
    "registrar_records": [
      {
        "type": "A",
        "name": "@",
        "value": "76.76.21.21",
        "ttl": 3600
      }
    ]
  },
  "ssl": {
    "active": true
  },
  "email": {
    "configured": false,
    "mx": []
  }
}

curl https://domani.run/api/domains/mysite.com/status \
  -H "Authorization: Bearer domani_sk_xxx"

Check email DNS health (MX, SPF, DMARC, DKIM)

Checks email DNS configuration for a domain: MX records, SPF, DMARC, and DKIM. Auto-detects the email provider from MX records (Google Workspace, Proton, Fastmail).

{
  "domain": "mysite.com",
  "provider": "google-workspace",
  "mx": {
    "configured": true,
    "records": [
      "1 aspmx.l.google.com",
      "5 alt1.aspmx.l.google.com"
    ]
  },
  "spf": {
    "configured": true,
    "value": "v=spf1 include:_spf.google.com ~all"
  },
  "dmarc": {
    "configured": true,
    "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@mysite.com"
  },
  "dkim": {
    "configured": true,
    "selectors": [
      "google"
    ]
  }
}

curl https://domani.run/api/domains/mysite.com/email/check \
  -H "Authorization: Bearer domani_sk_xxx"

Get owner-scoped email deliverability health

Separates deterministic authentication readiness, 30-day recipient-weighted delivery outcomes, account safety state, and measured provider placement. The readiness score is not an Inbox probability, and unmeasured placement is returned as not_tested.

curl https://domani.run/api/domains/mysite.com/email/deliverability \
  -H "Authorization: Bearer domani_sk_xxx"

Set up email on a domain

Pre-configure email DNS on a domain (optional). This is called automatically by create_mailbox when needed. Pass force=true to override existing email provider (Google Workspace, Fastmail, Proton).

Remove email from a domain

Remove email from a domain, delete all mailboxes and messages, and set emailEnabled to false.

Check email DNS status

Check email DNS verification status for a domain. Returns whether the domain is verified and ready, DNS record details, and mailbox count.

Create a mailbox on domani.run

Create a free email address on domani.run (e.g. hello@domani.run). No domain ownership required. Limited to 1 free @domani.run mailbox per user. Many common slugs are reserved.

List all mailboxes

List every mailbox the acting principal can access across all domains, including workspace grants.

Create a mailbox

Create an email address (mailbox). Provide a full address like "hello@mysite.com". Email DNS is auto-configured on first use. Pass force=true to override existing email provider. Max 5 mailboxes per user. For free @domani.run mailboxes use POST /api/email. Pass workspace_id to create the mailbox inside a workspace you own. For a custom domain, this explicitly and atomically adopts the domain and all its unscoped sibling mailboxes into that workspace; a domain can never be split across workspaces. Pass kind="hosted" to create a real IMAP/SMTP mailbox on your own domain (connect Apple Mail, Thunderbird, or any client) instead of the default API mailbox (send/receive via API + webhooks). Hosted mailboxes return DNS records to publish, mail client settings, and a one-time app password. Requires a domain you own.

List all mailboxes

List every mailbox the acting principal can access, including workspace grants. Same as GET /api/email.

Get mailbox details

Get details for a specific mailbox by its full email address (URL-encoded, e.g. hello%40mysite.com).

Update mailbox

Update a mailbox's display name, webhook URL, or forward-to email address by its full email address. Set to null to disable/clear.

Delete a mailbox

Delete a mailbox by its full email address. Requires confirm=true in body. Without confirm, returns a preview with message_count.

Send an email

Send an email from a mailbox identified by its full email address. The server runs a mandatory versioned policy first: objective safety failures are denied while reputation and content-quality findings are returned as warnings. Maximum 20 unique recipients per message. Rate limit: 100 recipients per hour per mailbox.

Preflight an outbound email

Run the exact versioned server-side policy used by the send endpoint without sending or consuming email quota. Public HTTPS authentication links on third-party domains are allowed with a reputation warning. Local/private URLs, non-HTTPS authentication links and executable attachments are blocked; bodies above 102 KB produce a clipping warning.

List emails

List emails in a canonical folder or virtual view. Defaults to Inbox. Folder location is independent from message direction and spam verdict. Authentication mail (OTPs / verification codes, password resets, magic links) is tagged security: "auth". Tokens without the email:auth_secrets scope see those messages with subject and body REDACTED (redacted: true) - metadata (from, date) stays visible.

List email folders and counts

Return server-derived counts for system folders and virtual views, plus lifecycle capabilities for the mailbox backend.

Apply a lifecycle action to messages

Move, restore, mark read, star, or permanently delete up to 100 explicit message IDs. Moving to Trash is reversible. Permanent deletion requires email:delete and only accepts messages already in Trash. Returns 207 when only part of the batch succeeds.

Mark messages as read or unread

Mark one or more messages as read or unread in a mailbox identified by its full email address.

Bulk delete messages

Move multiple messages to Trash. This is reversible and delegates to the canonical lifecycle action.

Get a message

Fetch a single message by ID from a mailbox identified by its full email address. Messages classified as authentication mail (OTP, password reset, magic link) come back with subject/body redacted unless the token has the email:auth_secrets scope.

Delete a message

Move a message to Trash. This is reversible. Use the lifecycle action with delete_permanently and an email:delete token to erase a message already in Trash.

Reply to a message

Reply to a message in a mailbox identified by its full email address. Threading headers are auto-populated.

Forward a message

Forward a message from a mailbox identified by its full email address to another recipient. Forwarding authentication mail (OTP, password reset, magic link) requires the email:auth_secrets scope - it would exfiltrate the secret.

Get mailbox avatar info

Returns the Gravatar URL (if set) and signup link for a mailbox identified by its full email address.

Get mailbox webhook config

Returns the webhook URL, signing secret, and status for a mailbox.

Set mailbox webhook

Set or update the inbound webhook URL for a mailbox. Incoming emails will be POSTed to this URL with HMAC-SHA256 signing.

Remove mailbox webhook

Remove the webhook URL and signing secret from a mailbox. Inbound emails will only be stored.

Rotate webhook signing secret

Regenerate the HMAC-SHA256 signing secret for a mailbox webhook. The old secret is immediately invalidated.

Test mailbox webhook

Send a signed test payload to the mailbox webhook URL. Returns HTTP status and whether delivery succeeded.

List mailbox aliases

List all alias addresses that deliver into a mailbox. Aliases let several addresses (sales@, hello@, contact@) share one inbox without using a mailbox slot.

Add a mailbox alias

Add an alias address that delivers into this mailbox, without using a mailbox slot. The alias must be on the same domain as the mailbox. Provide a bare slug ("sales") or a full address ("sales@mysite.com").

Remove a mailbox alias

Remove an alias from a mailbox. Email to that address stops being delivered.

Get mail client settings (hosted)

Get IMAP/SMTP connection settings for a hosted mailbox, to configure Apple Mail, Thunderbird, or any mail client. Username is the full address; the password is an app password (create one with POST /api/emails/{address}/credentials). Hosted mailboxes only.

List app passwords (hosted)

List the app passwords for a hosted mailbox. Secrets are shown only once at creation; this returns labels and metadata only. Hosted mailboxes only.

Create an app password (hosted)

Create an app password for a hosted mailbox, used as the password in a mail client (IMAP/SMTP). The secret is returned once - store it now. Hosted mailboxes only.

Revoke an app password (hosted)

Revoke an app password. Any mail client using it stops connecting immediately. Hosted mailboxes only.

List inbound mail rules

List a mailbox's inbound filtering rules, in the priority order they are applied (first match wins).

Add an inbound mail rule

Add a rule that runs on inbound messages matching a field (from/to/subject/body). Actions: drop, mark_read, forward (action_arg = address), webhook_only (skip forward-to), label (action_arg = label). Rules apply in priority order (lower first); first match wins.

Remove an inbound mail rule

Remove an inbound filtering rule from a mailbox.

Set domain catch-all

Route every email sent to an unmatched address on the domain into a designated mailbox. Anything that does not match a mailbox, subaddress, or alias lands in the catch-all. The mailbox must already exist on the domain.

Clear domain catch-all

Remove the catch-all on a domain. Email to unmatched addresses will be dropped again.

List suppressed addresses

List addresses on your suppression list - hard bounces and complaints (ingested automatically from delivery events) plus manual entries. Sends to these addresses are skipped. Cursor-paginated.

Add a suppression

Manually add an address to your suppression list so future sends skip it. Hard bounces and complaints are added automatically; use this for addresses you want to stop emailing. Idempotent.

Remove a suppression

Remove an address from your suppression list so you can email it again (e.g. after the recipient fixed their mailbox).

Add DNS records to verify domain ownership for a third-party service

Adds the correct DNS records (TXT, CNAME) to prove domain ownership to a third-party service. Supports Stripe, Google Search Console, AWS SES, Postmark, Resend, Facebook, HubSpot, and Microsoft 365. Unknown service names fall back to a generic TXT record. Records are merged with existing DNS - existing records are preserved.

{
  "domain": "mysite.com",
  "service": "stripe",
  "service_display_name": "Stripe",
  "known_service": true,
  "records_added": [
    {
      "type": "TXT",
      "name": "@",
      "value": "stripe-verification=abc123def456",
      "ttl": 3600
    }
  ],
  "total_records": 3,
  "docs": "https://docs.stripe.com/identity/verification-checks/selfie#domain-verification",
  "hint": "Stripe verification records added. Return to Stripe to complete verification."
}

curl -X POST https://domani.run/api/domains/mysite.com/verify-service \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service": "stripe", "token": "abc123def456"}'

List supported services for domain verification

Returns all known services with their names, descriptions, and documentation URLs. Unknown services fall back to a generic TXT record.

Look up domain registration data via RDAP

Queries the RDAP (Registration Data Access Protocol) network for domain registration data. Returns registrar, creation/expiry/update dates, days until expiry, status codes, nameservers, DNSSEC status, and contact information (registrant, admin, tech, billing, abuse). Works for any domain - no ownership required. RDAP is the modern, JSON-native replacement for WHOIS. Falls back to WHOIS (port 43) for TLDs without RDAP, and supplements RDAP with WHOIS referral data when contacts are missing (common post-GDPR). Contact information may be partially or fully redacted due to GDPR or privacy protection services. Public endpoint - no authentication required. Authenticated requests get higher rate limits (30/min vs 10/min).

curl "https://domani.run/api/domains/whois?q=google.com"

Get website preview metadata for a domain

Returns Open Graph metadata (title, description, image, favicon) for a domain. Data is lazily fetched and cached for 7 days. First request for a domain may take 1-5s (live fetch); subsequent requests are instant (cache hit). Returns null fields if the site is unreachable or has no OG tags. Public endpoint - no authentication required.

curl "https://domani.run/api/domains/google.com/og"

List your API tokens

Returns all API tokens for the authenticated user. Keys are masked for security (first 12 + last 4 characters visible). Use this to audit active tokens.

{
  "tokens": [
    {
      "id": "cm5abc123",
      "name": "Default",
      "key": "domani_sk_a...wxyz",
      "lastUsed": "2025-02-18T10:30:00.000Z",
      "expiresAt": null,
      "expired": false,
      "scopes": [
        "*"
      ],
      "createdAt": "2025-01-15T10:30:00.000Z",
      "max_per_tx": null,
      "max_per_month": null,
      "spent_this_month": 0,
      "parent_token_id": null,
      "agent_identity": null
    },
    {
      "id": "cm5def456",
      "name": "CI/CD",
      "key": "domani_sk_b...vwxy",
      "lastUsed": null,
      "expiresAt": "2025-05-01T14:00:00.000Z",
      "expired": false,
      "scopes": [
        "domains:read",
        "domains:write"
      ],
      "createdAt": "2025-02-01T14:00:00.000Z"
    }
  ]
}

curl https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx"

Create a new API token

Creates a new API token. The full key is returned only in this response - store it securely. You can create multiple tokens to separate access for different applications.

{
  "id": "cm5ghi789",
  "name": "CI/CD Pipeline",
  "key": "domani_sk_x1Y2z3A4b5C6d7E8f9G0hIjK",
  "expiresAt": "2025-03-20T10:30:00.000Z",
  "scopes": [
    "domains:read",
    "domains:write"
  ],
  "createdAt": "2025-02-18T10:30:00.000Z",
  "max_per_tx": 25,
  "max_per_month": 100
}

curl -X POST https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline"}'

Revoke an API token

Permanently revokes an API token. Any applications using this token will immediately lose access. This action cannot be undone.

{
  "success": true
}

curl -X DELETE https://domani.run/api/tokens/cm5abc123 \
  -H "Authorization: Bearer domani_sk_xxx"

List security audit events

Returns the account's security audit trail, newest first: token lifecycle (created, revoked, escalation attempts), spend-cap and max_price denials, charges, payout requests, and blocked account deletions. Use it to monitor what your agents' tokens are doing.

{
  "events": [
    {
      "id": "evt1",
      "tokenId": "cm5abc123",
      "type": "purchase.charged",
      "targetType": "domain",
      "targetId": "mysite.com",
      "metadata": {
        "amountCents": 1450,
        "operation": "buy",
        "method": "card"
      },
      "createdAt": "2026-07-11T10:00:00.000Z"
    },
    {
      "id": "evt2",
      "tokenId": "cm5abc123",
      "type": "purchase.denied_cap",
      "targetType": "domain",
      "targetId": "expensive.ai",
      "metadata": {
        "amountCents": 8470
      },
      "createdAt": "2026-07-11T09:58:00.000Z"
    }
  ],
  "next_cursor": null,
  "hint": "Security-relevant events for this account."
}

curl "https://domani.run/api/audit?limit=50" \
  -H "Authorization: Bearer domani_sk_xxx"

Get checkout URL for adding a payment method

Creates a checkout session for adding a credit card. Redirect the user to the returned URL. This is required before purchasing domains. After the user completes checkout, they are redirected back to the dashboard.

{
  "url": "https://checkout.domani.run/session/cs_abc123...",
  "hint": "Open this URL in a browser to add your payment card."
}

curl -X POST https://domani.run/api/billing/setup \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"mode": "checkout"}'

Remove saved payment method

Detaches the user's saved credit card from their account. After removal, a new card must be added before purchasing domains.

{
  "removed": true
}

curl -X DELETE https://domani.run/api/billing/card \
  -H "Authorization: Bearer domani_sk_xxx"

Get marketplace payout status

Returns the seller's Stripe Connect onboarding status and available marketplace balance. payouts_enabled is true once onboarding is complete and the seller can receive bank payouts.

{
  "onboarded": true,
  "payouts_enabled": true,
  "details_submitted": true,
  "balance_cents": 45000
}

curl https://domani.run/api/billing/connect \
  -H "Authorization: Bearer domani_sk_xxx"

Start bank payout onboarding

Creates (or resumes) Stripe Connect Express onboarding for a marketplace seller and returns a hosted onboarding URL to redirect the user to. Required before a seller can withdraw earnings to their bank.

{
  "url": "https://connect.stripe.com/setup/e/acct_123/..."
}

curl -X POST https://domani.run/api/billing/connect \
  -H "Authorization: Bearer domani_sk_xxx"

Withdraw marketplace balance to bank

Transfers the seller's entire available marketplace balance to their connected bank account. Requires completed payout onboarding (POST /api/billing/connect). The balance is reserved before the transfer and restored if it fails, so a failure never loses funds.

{
  "amount_cents": 45000,
  "transfer_id": "tr_123"
}

curl -X POST https://domani.run/api/billing/connect/payout \
  -H "Authorization: Bearer domani_sk_xxx"

List payment invoices

Returns a list of paid invoices with invoice number, amount, date, and links to view or download the PDF. Invoices are generated automatically for every domain purchase, renewal, and transfer.

curl https://domani.run/api/billing/invoices \
  -H "Authorization: Bearer domani_sk_xxx"

Get referral earnings and history

Returns your unique referral code, commission rate (20%), earnings breakdown (total, paid, pending), and a history of all referred purchases. Share your referral code with others - when they register with your code (via the ref parameter), you earn a commission on all their future domain purchases automatically.

{
  "referral_code": "x7k9m2",
  "referral_rate": 20,
  "total_earned_cents": 400,
  "total_paid_cents": 200,
  "total_pending_cents": 200,
  "referrals": [
    {
      "id": "cm5ref001",
      "domains": [
        "friend-site.com"
      ],
      "earned_cents": 200,
      "paid_out": true,
      "created_at": "2025-01-20T10:00:00.000Z"
    },
    {
      "id": "cm5ref002",
      "domains": [
        "another.dev"
      ],
      "earned_cents": 200,
      "paid_out": false,
      "created_at": "2025-02-10T15:30:00.000Z"
    }
  ]
}

curl https://domani.run/api/referrals \
  -H "Authorization: Bearer domani_sk_xxx"

Place a backorder on a taken domain

Watches a domain that is currently registered to someone else and automatically registers it for you when it becomes available (drops) - availability is polled every few minutes, so the catch lands within minutes of the drop. You are charged only if and when the catch succeeds - no upfront fee. A price cap protects you from a registration-price spike between now and the drop. Requires a payment method on file (card) or payment_method: "balance" so the catch can be paid when it happens. Best-effort: a contested drop may be taken by a specialized drop-catcher first.

curl -X POST https://domani.run/api/backorders \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "taken.com"}'

List your backorders

Returns your backorders, newest first. Filter by status (watching, caught, failed, cancelled, expired).

Get a backorder

Cancel a backorder

Stops watching a domain. Only backorders in the watching state can be cancelled.

List a domain for sale (open marketplace)

List any domain for sale on the Domani marketplace, including domains on other registrars. Domains already in your Domani account are auto-verified and listed immediately (status active). External domains require TXT ownership verification (status pending_verification). Fees: 10% platform commission on successful sales. Requires deals:write scope.

Verify TXT ownership for external listing

Verify that the TXT ownership record has been added for an external domain listing. On success, the listing status changes from pending_verification to active and becomes buyable. Requires deals:write scope.

Check listing and deal status

Check the status of a domain listing and any active deal. Returns listing details, deal pipeline status, and contextual hints. Requires deals:read scope.

List your deals

List marketplace deals where you are the buyer or seller. Filter by role or status. Requires deals:read scope.

Purchase an external domain (create deal)

Create an escrow deal to purchase a domain listed on the marketplace. Buyer's payment is held in escrow until the domain transfer completes. The seller is notified and has 7 days to provide the EPP/auth code. Requires domains:transfer scope.

Get deal detail with timeline

Get full details of a deal including price breakdown, deadlines, and event timeline. Both buyer and seller can access their deals. Requires deals:read scope.

Provide EPP/auth code (seller)

Seller provides the EPP/authorization code to initiate the domain transfer. The code is encrypted at rest and used to start the registrar transfer. Max 3 attempts. Requires deals:write scope.

Get a deal receipt / statement

Returns a role-aware invoice for a marketplace deal. Buyers get a purchase receipt; sellers get a statement showing the sale, the platform commission line, and the net payout. Works for every payment method (card/USDC/balance). Requires deals:read scope.

List your negotiations

Lists price negotiations where you are the buyer or seller. Counterparties are anonymized (roles only). Requires deals:read scope.

Make an offer on a listing

Opens an anonymous price negotiation on an actively-listed domain with an initial offer. The seller can counter, accept, or decline. On acceptance the buyer finalizes payment and a deal is created at the agreed price. Requires deals:write scope.

curl -X POST https://domani.run/api/negotiations \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","offer":500}'

Get a negotiation thread

Returns a negotiation with its full offer thread, anonymized (offers are labelled 'you' or 'counterparty'). Requires deals:read scope.

Counter, accept, or decline

Respond to the current offer on the table when it's your turn. counter requires a new amount; accept locks the price at the amount currently on the table; decline ends the negotiation. Requires deals:write scope.

Withdraw a negotiation

Buyer withdraws an open or agreed negotiation. Requires deals:write scope.

Finalize an agreed negotiation (pay)

Buyer pays the agreed price to create the escrow deal, then the standard transfer flow runs. Accepts the same payment methods as a marketplace purchase (card, USDC, x402). Returns 402 with payment instructions if no payment is provided. For a broker-sourced acquisition, if the agreed price is above the max_budget you set, returns 409 BUDGET_EXCEEDED - re-submit with confirm_over_budget: true to proceed. Requires domains:transfer scope.

List your broker requests

Lists your domain acquisition requests and their status. Requires deals:read scope.

Request acquisition of a taken domain

Ask domani to acquire a specific taken, unlisted domain on your behalf. Agents source the owner via RDAP, reach out anonymously, and negotiate - commission-only, no upfront fee. Owner interest opens an anonymous negotiation. Note: many owners are unreachable (GDPR-redacted WHOIS) - the request then ends no_contact. Requires deals:write scope.

curl -X POST https://domani.run/api/broker \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain":"dream.com","max_budget":5000}'

Get a broker request

Returns one of your broker requests. Requires deals:read scope.

Cancel a broker request

Cancels an active domain acquisition request. Requires deals:write scope.

Read a broker inquiry's state (owner side)

The owner-agent read path: poll the current, anonymized state of an inquiry with your token before acting. Returns the domain, the buyer's offer on the table, whose move it is, and the actions available now. Never exposes the buyer's identity or budget. Token-authorized.

curl "https://domani.run/api/broker/respond?token=<from your inbox>"

Respond to a broker inquiry (owner side)

The owner-agent path: respond to a broker's acquisition inquiry using the token from the outreach email delivered to your inbox - the fully autonomous alternative to replying by email or clicking the human claim link. offer/counter open or advance an anonymous negotiation at your asking price; decline and opt_out end it. Token-authorized (the token is the capability) - no account or scope required.

curl -X POST https://domani.run/api/broker/respond \
  -H "Content-Type: application/json" \
  -d '{"token":"<from your inbox>","action":"offer","price":800}'

List notifications

List your in-app notifications with cursor-based pagination. Includes deal events, listing updates, and system alerts. Requires notifications:read scope.

Get unread notification count

Lightweight endpoint for polling unread notification count. Requires notifications:read scope.

{
  "unread_count": 3
}

Mark notification as read

Mark a single notification as read. Requires notifications:read scope.

Mark all notifications as read

Mark all unread notifications as read. Requires notifications:read scope.

Get notification preferences

Returns the user's notification preferences for each category and channel (in_app, email). Missing preferences default to enabled. Requires notifications:read scope.

Update notification preferences

Update notification preferences for specific categories and channels. Requires notifications:read scope.

List webhooks

List all webhook endpoints configured for your account. Returns URL, subscribed events, and active status for each webhook. Secrets are never returned after creation.

{
  "webhooks": [
    {
      "id": "cm5wh001",
      "url": "https://example.com/webhooks/domani",
      "events": [
        "domain.purchased",
        "dns.updated"
      ],
      "active": true,
      "created_at": "2026-02-25T10:00:00.000Z"
    }
  ],
  "hint": "1 webhook(s)."
}

curl https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx"

Create webhook

Register a new webhook endpoint. The URL must use HTTPS. Choose which event types to subscribe to. The webhook secret is returned only once at creation - save it to verify incoming payloads with HMAC-SHA256. Maximum 5 webhooks per account.

{
  "id": "cm5wh001",
  "url": "https://example.com/webhooks/domani",
  "events": [
    "domain.purchased",
    "dns.updated"
  ],
  "secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "active": true,
  "created_at": "2026-02-25T10:00:00.000Z",
  "hint": "Webhook created. Save the secret - it won't be shown again. Use it to verify incoming payloads with HMAC-SHA256."
}

curl -X POST https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["domain.purchased","dns.updated"]}'

Update webhook

Update a webhook's URL, subscribed events, or active status. Send only the fields you want to change.

Delete webhook

Delete a webhook endpoint. All pending deliveries will be cancelled. This cannot be undone.

List webhook deliveries

Get recent delivery attempts for a webhook. Shows event type, HTTP status, number of attempts, and any errors. Useful for debugging failed deliveries.

{
  "deliveries": [
    {
      "id": "cm5del001",
      "event_type": "domain.purchased",
      "status": "delivered",
      "http_status": 200,
      "attempts": 1,
      "last_error": null,
      "created_at": "2026-02-25T10:05:00.000Z"
    }
  ],
  "hint": "1 delivery(ies) for this webhook."
}

List webhook event types

List all available webhook event types with descriptions. No authentication required.

{
  "events": [
    {
      "type": "domain.purchased",
      "description": "A new domain was successfully registered"
    },
    {
      "type": "dns.updated",
      "description": "DNS records were changed for a domain"
    },
    {
      "type": "transfer.completed",
      "description": "A domain transfer completed successfully"
    }
  ]
}

curl https://domani.run/api/webhooks/events

Request a workspace ownership transfer

Owner-only. Sends a 48-hour acceptance link to an existing member. Nothing moves until that authenticated member accepts.

Revoke a pending ownership transfer

Accept workspace ownership

Target-only. Atomically transfers the workspace, scoped domains and mailboxes; the previous owner becomes an admin and the existing payer remains unchanged.