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 and all associated data

Permanently delete the authenticated user's account, all domains, tokens, webhooks, and other associated data. 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"

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": {
    "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.

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.

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

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

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"

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"

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 all email addresses (mailboxes) owned by the user across all domains.

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.

List all mailboxes

List all email addresses (mailboxes) owned by the user across all domains. 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. Rate limit: 100 emails per hour per mailbox.

List emails

List emails sent and received by a mailbox identified by its full email address. Supports cursor-based pagination and direction filtering.

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

Soft-delete multiple messages at once in a mailbox identified by its full email address.

Get a message

Fetch a single message by ID from a mailbox identified by its full email address.

Delete a message

Soft-delete a message from a mailbox identified by its full email address.

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.

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.

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"
    },
    {
      "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"
}

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"

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"

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"

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