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.sh/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.sh/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, referral code, and usage counts. Agents should call this after authentication to check has_payment_method before attempting purchases.

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

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

List all available TLDs with pricing

Returns all 898+ 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": 898,
  "offset": 0,
  "limit": null
}

curl https://domani.sh/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.sh/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.sh/api/domains/suggest?prompt=AI+coding+assistant"

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"
    },
    {
      "domain": "myapp.dev",
      "status": "active",
      "purchasedAt": "2025-02-01T14:00:00.000Z",
      "expiresAt": "2026-02-01T14:00:00.000Z"
    }
  ]
}

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

Purchase one or more domains

Purchases one or more domains and registers them immediately. Send {"domain": "..."} for single or {"domains": ["...", "..."]} for bulk (max 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 two payment methods: 1. Card (default): Requires a card on file via POST /api/billing/setup. Charged per domain. 2. x402 USDC (single domain only): Include a PAYMENT-SIGNATURE header with a signed USDC payment on Base. Bulk purchases require a card on file (x402 not supported for multi-domain). If neither payment method is available for single domain, returns HTTP 402 with x402 payment requirements.

{
  "domain": "mysite.com",
  "status": "active",
  "expires": "2026-02-18T00:00:00.000Z",
  "price": 10.88,
  "currency": "USD",
  "payment_method": "stripe"
}

curl -X POST https://domani.sh/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": "stripe",
  "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.sh/api/domains/mysite.com \
  -H "Authorization: Bearer domani_sk_xxx"

Update domain settings

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

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

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.

Transfer domain from another provider (Preview)

Initiate a domain transfer-in. Requires the authorization/EPP code from the current provider. Transfer typically takes 1-5 days to complete. Payment is charged upfront (card or USDC on Base via x402). > Preview - coming soon. This feature is not currently available.

curl -X POST https://domani.sh/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 (Preview)

Renew a domain you own for additional years (1-10). Payment is charged upfront. The new expiry date is returned in the response. > Preview - coming soon. This feature is not currently available.

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

Get DNS records for a domain you own

Returns all DNS records configured for a domain you own. Includes A, AAAA, CNAME, MX, TXT, NS, and other record types.

{
  "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": "mail.example.com",
      "ttl": 3600,
      "priority": 10
    }
  ]
}

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

Set DNS records for a domain you own

Replaces all DNS records for a domain you own. Send the complete set of records - any existing records not included will be removed.

{
  "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.sh/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}
  ]}'

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.sh/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.sh/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.sh/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.sh/api/domains/mysite.com/email/check \
  -H "Authorization: Bearer domani_sk_xxx"

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.sh/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.sh/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.sh/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",
      "createdAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "cm5def456",
      "name": "CI/CD",
      "key": "domani_sk_b...vwxy",
      "lastUsed": null,
      "createdAt": "2025-02-01T14:00:00.000Z"
    }
  ]
}

curl https://domani.sh/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",
  "createdAt": "2025-02-18T10:30:00.000Z"
}

curl -X POST https://domani.sh/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.sh/api/tokens/cm5abc123 \
  -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..."
}

curl -X POST https://domani.sh/api/billing/setup \
  -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.sh/api/referrals \
  -H "Authorization: Bearer domani_sk_xxx"