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://dev.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://dev.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://dev.domani.run/api/me \
  -H "Authorization: Bearer domani_sk_xxx"

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://dev.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://dev.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"}'

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://dev.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://dev.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://dev.domani.run/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://dev.domani.run/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 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.

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

curl -X POST https://dev.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": {
    "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://dev.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://dev.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.

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.

Transfer domain from another provider

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 via card or USDC (two-step: get 402, send USDC, retry with payment_tx + payment_chain).

curl -X POST https://dev.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://dev.domani.run/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://dev.domani.run/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://dev.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}
  ]}'

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

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

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://dev.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://dev.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://dev.domani.run/api/webhooks/events