{"openapi":"3.1.0","info":{"title":"domani.run API","version":"1.0.0","description":"Domain infrastructure for AI agents. One API to search, register, and connect domain names.\n\n## Authentication\n\nAll authenticated endpoints require a Bearer token:\n\n```\nAuthorization: Bearer domani_sk_xxx\n```\n\nGet your API key by registering:\n\n```bash\ncurl -X POST https://domani.run/api/auth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"you@example.com\"}'\n```\n\n## Rate Limits\n\nEvery response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. When rate limited (HTTP 429), check the `Retry-After` header for seconds to wait.\n\n## Error Handling\n\nAll errors return a consistent JSON envelope with `error`, `code`, `hint`, and `documentation_url` fields. Use the `code` field for programmatic handling and the `hint` field for recovery guidance.\n\n## MCP Server\n\nA real-time MCP (Model Context Protocol) server is available at `POST /mcp` using Streamable HTTP transport. Connect any MCP-compatible agent (Claude Code, Cursor, etc.) with your Bearer token for typed tool access (search, buy, DNS, etc.).\n\n## Pagination\n\nThe `GET /api/tlds` endpoint supports `limit` and `offset` query parameters. When paginated, the response includes a `Link` header with `rel=\"next\"` for the next page.","contact":{"name":"domani.run","url":"https://domani.run"}},"servers":[{"url":"https://domani.run","description":"Production"}],"externalDocs":{"description":"Interactive API Reference","url":"https://domani.run/docs"},"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"domani_sk_xxx","description":"API key obtained from POST /api/auth/register. Include as: `Authorization: Bearer domani_sk_xxx`. Keys use the prefix `domani_sk_` followed by 32 random characters."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["MISSING_API_KEY","INVALID_API_KEY","EXPIRED_API_KEY","MISSING_PARAMETER","INVALID_DOMAIN","PAYMENT_REQUIRED","DOMAIN_UNAVAILABLE","RATE_LIMIT_EXCEEDED","USER_EXISTS","NOT_FOUND","UNKNOWN_PROVIDER","UNKNOWN_METHOD","TARGET_REQUIRED","INVALID_PARAMETER","CONTACT_REQUIRED","INVALID_CONTACT","INSUFFICIENT_SCOPE","SCOPE_ESCALATION","DOMAIN_EXISTS","DOMAIN_NOT_ACTIVE","UNSUPPORTED_TLD","NOT_AVAILABLE","ALREADY_REGISTERED","TRANSFER_NOT_ELIGIBLE","ALREADY_LISTED","LISTING_SOLD","SELF_PURCHASE","DESCRIPTION_TOO_LONG","DEAL_NOT_FOUND","INVALID_DEAL_STATE","EPP_ATTEMPTS_EXCEEDED","ACTIVE_DEAL_EXISTS"]},"hint":{"type":"string","description":"Actionable recovery guidance for the caller"},"fix_command":{"type":"string","description":"CLI command to resolve the error (e.g. 'domani login', 'domani billing'). Present in CLI --json output."},"documentation_url":{"type":"string","format":"uri","description":"Link to relevant documentation"},"setup_url":{"type":"string","format":"uri","description":"URL to resolve the issue (e.g. add payment method)"},"fix_url":{"type":"string","format":"uri","description":"URL to resolve the issue (alias for setup_url in CLI --json output)"},"retry_after":{"type":"integer","description":"Seconds until retry is allowed (present on 429 responses)"}},"required":["error","code","documentation_url"],"example":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"SearchResult":{"type":"object","properties":{"available":{"type":"boolean","description":"Whether the domain is available for registration"},"domain":{"type":"string","example":"example.com","description":"Full domain name including TLD"},"price":{"type":"number","example":10.88,"description":"Registration price in the specified currency"},"currency":{"type":"string","example":"USD","description":"ISO 4217 currency code (always USD)"},"error":{"type":"boolean","description":"True if RDAP lookup failed (availability unknown)"},"for_sale":{"type":"object","description":"Present when the domain is listed for sale (either on Domani marketplace or detected on an external aftermarket)","properties":{"price":{"type":"number","example":5000,"description":"Listed sale price in USD"},"currency":{"type":"string","example":"USD","description":"Price currency (always USD)"},"source":{"type":"string","example":"domani","description":"Where the listing originates: 'domani' for Domani marketplace, or aftermarket name (e.g. 'Sedo', 'Afternic')"},"buyable":{"type":"boolean","example":true,"description":"Whether the domain can be purchased directly via the Domani API. true for Domani listings, false for external aftermarket"},"url":{"type":"string","example":"https://sedo.com/search/details/?domain=example.com","description":"Direct link to external aftermarket listing (only present for external sources)"},"description":{"type":"string","description":"Listing description (Domani marketplace listings only)"}},"required":["price","currency","source","buyable"]}},"required":["available","domain","price","currency"]},"TldInfo":{"type":"object","properties":{"tld":{"type":"string","example":"com","description":"Top-level domain without dot prefix"},"registration":{"type":"number","example":10.88,"description":"First-year registration price in USD"},"renewal":{"type":"number","example":13.08,"description":"Annual renewal price in USD"},"transfer":{"type":"number","example":13.08,"description":"Transfer price in USD"}},"required":["tld","registration","renewal","transfer"]},"DnsRecord":{"type":"object","properties":{"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SRV","CAA"],"description":"DNS record type"},"name":{"type":"string","example":"@","description":"Record name (@ for root, or subdomain)"},"value":{"type":"string","example":"76.76.21.21","description":"Record value (IP address, hostname, etc.)"},"ttl":{"type":"integer","example":3600,"description":"Time to live in seconds"},"priority":{"type":"integer","description":"Priority value (required for MX records)"}},"required":["type","name","value","ttl"]},"DomainRecord":{"type":"object","properties":{"domain":{"type":"string","example":"mysite.com"},"status":{"type":"string","enum":["active","expired","pending"],"description":"Current registration status"},"auto_renew":{"type":"boolean","description":"Whether auto-renew is enabled"},"purchasedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"emailEnabled":{"type":"boolean","description":"Whether email is set up for this domain"},"emailVerified":{"type":"boolean","description":"Whether email DNS records have been verified"},"emailVerifiedAt":{"type":"string","format":"date-time","nullable":true,"description":"When email DNS was verified (null if not yet verified)"},"mailboxCount":{"type":"integer","description":"Number of mailboxes configured for this domain"}},"required":["domain","status","auto_renew","purchasedAt","expiresAt","emailEnabled","emailVerified","mailboxCount"]},"DomainDetail":{"type":"object","description":"Detailed domain information","properties":{"domain":{"type":"string","example":"mysite.com"},"status":{"type":"string","enum":["active","expired","pending"]},"auto_renew":{"type":"boolean","description":"Whether auto-renew is enabled"},"purchased_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"days_until_expiry":{"type":"integer","description":"Days until domain expiry"},"payment_method":{"type":"string","enum":["card","x402","crypto"],"description":"How the domain was paid for"},"payment_tx":{"type":"string","nullable":true,"description":"On-chain tx hash (USDC payments)"},"registrar":{"type":"object","nullable":true,"description":"Domain registration details (null if unavailable)","properties":{"security_lock":{"type":"boolean","description":"Whether the domain is locked against transfers"},"whois_privacy":{"type":"boolean","description":"Whether WHOIS privacy is enabled"},"auto_renew":{"type":"boolean","description":"Auto-renew status"},"create_date":{"type":"string","description":"Domain creation date"},"expire_date":{"type":"string","description":"Domain expiration date"}}}},"required":["domain","status","auto_renew","purchased_at","expires_at","days_until_expiry","payment_method"]},"TokenInfo":{"type":"object","properties":{"id":{"type":"string","description":"Unique token identifier (use this for DELETE)"},"name":{"type":"string","example":"CLI","description":"Human-readable token label"},"key":{"type":"string","example":"domani_sk_...wxyz","description":"Masked API key (full key shown only on creation)"},"lastUsed":{"type":"string","format":"date-time","nullable":true,"description":"Last time this token was used"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"When this token expires (null = never)"},"expired":{"type":"boolean","description":"Whether this token has expired"},"scopes":{"type":"array","items":{"type":"string"},"description":"Permission scopes granted to this token. ['*'] means full access."},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","key","createdAt"]},"Contact":{"type":"object","description":"Contact information for a domain role (may be redacted due to GDPR/privacy services)","properties":{"name":{"type":"string","nullable":true,"description":"Contact name"},"organization":{"type":"string","nullable":true,"description":"Organization name"},"email":{"type":"string","nullable":true,"description":"Contact email"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"fax":{"type":"string","nullable":true,"description":"Fax number"},"street":{"type":"string","nullable":true,"description":"Street address"},"city":{"type":"string","nullable":true,"description":"City"},"state":{"type":"string","nullable":true,"description":"State or province"},"postal_code":{"type":"string","nullable":true,"description":"Postal/ZIP code"},"country":{"type":"string","nullable":true,"description":"Country code or name"}}},"RegistrantContact":{"type":"object","description":"WHOIS registrant contact information required for domain registration (ICANN requirement)","properties":{"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"org_name":{"type":"string","nullable":true,"description":"Organization name (optional)"},"address1":{"type":"string","description":"Street address line 1"},"address2":{"type":"string","nullable":true,"description":"Street address line 2 (optional)"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State or province"},"postal_code":{"type":"string","description":"Postal/ZIP code"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. US, GB, FR)"},"phone":{"type":"string","description":"Phone in +CC.NUMBER format (e.g. +1.5551234567)"},"email":{"type":"string","format":"email","description":"Contact email address"}},"required":["first_name","last_name","address1","city","state","postal_code","country","phone","email"]},"AccountInfo":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"has_payment_method":{"type":"boolean","description":"Whether the user has a card on file (required before buying domains)"},"has_contact":{"type":"boolean","description":"Whether the user has set WHOIS contact info (required before purchasing domains)"},"contact":{"$ref":"#/components/schemas/RegistrantContact","description":"Registrant contact info (null if not set)"},"referral_code":{"type":"string","description":"Your unique referral code"},"referral_rate":{"type":"integer","description":"Commission percentage on referred purchases"},"domain_count":{"type":"integer","description":"Number of domains owned"},"token_count":{"type":"integer","description":"Number of active API tokens"},"created_at":{"type":"string","format":"date-time"}},"required":["id","email","has_payment_method","has_contact","referral_code","referral_rate","domain_count","token_count","created_at"]}},"headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}}},"paths":{"/api/auth/register":{"post":{"operationId":"registerUser","summary":"Create a new account","description":"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.","tags":["Authentication"],"security":[],"x-rateLimit":{"limit":5,"window":"1 minute","scope":"IP address"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/auth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"dev@example.com\"}'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"dev@example.com"},"ref":{"type":"string","description":"Referral code - permanently links this user to the referrer. The referrer earns a commission on every domain purchase.","example":"x7k9m2"}},"required":["email"]},"example":{"email":"dev@example.com","ref":"x7k9m2"}}}},"responses":{"201":{"description":"Account created successfully","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"Your API key - save this securely"},"referral_code":{"type":"string","description":"Your unique referral code for earning commissions"},"has_payment_method":{"type":"boolean","description":"Whether the user has a card on file (always false for new accounts)"},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"}}}}},"example":{"api_key":"domani_sk_a1B2c3D4e5F6g7H8i9J0kLmN","referral_code":"x7k9m2","has_payment_method":false,"user":{"id":"cm5abc123","email":"dev@example.com"}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Email is required","code":"MISSING_PARAMETER","hint":"Provide an 'email' field in the request body","documentation_url":"https://domani.run/llms.txt"}}}},"409":{"description":"User already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"User already exists","code":"USER_EXISTS","hint":"Use POST /api/auth/login to sign in instead","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/auth/login":{"post":{"operationId":"loginUser","summary":"Send a magic link sign-in email","description":"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.","tags":["Authentication"],"security":[],"x-rateLimit":{"limit":10,"window":"1 minute","scope":"IP address"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"dev@example.com\"}'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]},"example":{"email":"dev@example.com"}}}},"responses":{"200":{"description":"Magic link sent - check your email","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"message":{"type":"string"}}},"example":{"ok":true,"message":"Check your email for a sign-in link."}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Email is required","code":"MISSING_PARAMETER","hint":"Provide an 'email' field in the request body","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/auth/verify":{"get":{"operationId":"verifyMagicLink","summary":"Verify a magic link token","description":"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.","tags":["Authentication"],"security":[],"parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"Magic link token from email (base64url-encoded)"}],"responses":{"307":{"description":"Redirect to dashboard with auth credentials in query parameters"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Token is required","code":"MISSING_PARAMETER","hint":"Include the 'token' query parameter","documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/me":{"get":{"operationId":"getAccount","summary":"Get current account details","description":"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.","tags":["Account"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/me \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"responses":{"200":{"description":"Account details","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountInfo"},"example":{"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"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"put":{"operationId":"updateAccount","summary":"Update account preferences","description":"Update the authenticated user's account preferences such as preferred payment method.","tags":["Account"],"x-rateLimit":{"limit":20,"window":"1 minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preferred_payment_method":{"type":"string","enum":["card","usdc"],"nullable":true,"description":"Default payment method for purchases (card, usdc, or null for auto-select)"}},"required":["preferred_payment_method"]}}}},"responses":{"200":{"description":"Preferences updated","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"preferred_payment_method":{"type":"string","nullable":true},"hint":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"delete":{"operationId":"deleteAccount","summary":"Delete account and all associated data","description":"Permanently delete the authenticated user's account, all domains, tokens, webhooks, and other associated data. This action cannot be undone.","tags":["Account"],"x-rateLimit":{"limit":5,"window":"1 minute"},"responses":{"200":{"description":"Account deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"hint":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/me/contact":{"get":{"operationId":"getContact","summary":"Get registrant contact info","description":"Returns the authenticated user's WHOIS registrant contact information. Must be set before purchasing or transferring domains.","tags":["Account"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/me/contact \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"responses":{"200":{"description":"Contact information","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"has_contact":{"type":"boolean"},"contact":{"$ref":"#/components/schemas/RegistrantContact","nullable":true}}},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"put":{"operationId":"setContact","summary":"Set registrant contact info","description":"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.","tags":["Account"],"x-rateLimit":{"limit":10,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X PUT https://domani.run/api/me/contact \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -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\"}'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrantContact"}}}},"responses":{"200":{"description":"Contact info saved","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/RegistrantContact"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Missing required field: first_name","code":"INVALID_CONTACT","hint":"All required fields must be provided. Phone format: \"+CC.NUMBER\"","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/me/resend-verification":{"post":{"operationId":"resendEmailVerification","summary":"Resend contact email verification","description":"Resend the verification email for the account's contact email address. Rate limited to once per 15 minutes per email.","tags":["Account"],"x-rateLimit":{"limit":4,"window":"1 minute"},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address to verify (defaults to account contact email)"}}}}}},"responses":{"200":{"description":"Verification email sent or already verified","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"},"already_verified":{"type":"boolean"},"hint":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/tlds":{"get":{"operationId":"listTlds","summary":"List all available TLDs with pricing","description":"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).","tags":["TLDs"],"security":[],"x-rateLimit":{"limit":30,"window":"1 minute","scope":"IP address (unauthenticated), 60/min per user (authenticated)"},"x-codeSamples":[{"lang":"bash","label":"cURL - cheap TLDs sorted by price","source":"curl https://domani.run/api/tlds?max_price=10&sort=price"}],"parameters":[{"name":"max_price","in":"query","schema":{"type":"number","example":15},"description":"Maximum registration price in USD"},{"name":"min_price","in":"query","schema":{"type":"number","example":1},"description":"Minimum registration price in USD"},{"name":"sort","in":"query","schema":{"type":"string","enum":["tld","price","renewal"],"default":"tld"},"description":"Sort field - 'tld' (alphabetical), 'price' (registration), or 'renewal'"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort order"},{"name":"search","in":"query","schema":{"type":"string","example":"dev"},"description":"Filter TLD names containing this string"},{"name":"limit","in":"query","schema":{"type":"integer","example":20},"description":"Max results per page"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"example":0},"description":"Number of results to skip"}],"responses":{"200":{"description":"Paginated TLD list with pricing","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Link":{"description":"Pagination link (rel=\"next\") - present when more results exist","schema":{"type":"string"},"example":"</api/tlds?limit=20&offset=20&sort=price>; rel=\"next\""}},"content":{"application/json":{"schema":{"type":"object","properties":{"tlds":{"type":"array","items":{"$ref":"#/components/schemas/TldInfo"}},"total":{"type":"integer","description":"Total matching TLDs (before pagination)"},"offset":{"type":"integer"},"limit":{"type":"integer","nullable":true}}},"example":{"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}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/search":{"get":{"operationId":"search","summary":"Check availability and pricing for domains","description":"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).","tags":["Domain Search"],"security":[],"x-rateLimit":{"limit":20,"window":"1 minute","scope":"IP address (unauthenticated), 60/min per user (authenticated)"},"x-codeSamples":[{"lang":"bash","label":"Single domain","source":"curl \"https://domani.run/api/domains/search?q=mysite.com\""},{"lang":"bash","label":"Multiple domains","source":"curl \"https://domani.run/api/domains/search?domains=myapp.com,myapp.dev,myapp.ai&max_price=20\""},{"lang":"bash","label":"SSE streaming","source":"curl -H \"Accept: text/event-stream\" \"https://domani.run/api/domains/search?domains=myapp.com,myapp.dev,myapp.ai\""}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","example":"mysite.com"},"description":"Single domain including TLD (shorthand - returns flat object). Mutually exclusive with `domains`."},{"name":"domains","in":"query","schema":{"type":"string","example":"myapp.com,myapp.dev,myapp.ai"},"description":"Comma-separated list of full domain names to check (max 200). Returns array result."},{"name":"max_price","in":"query","schema":{"type":"number","example":20},"description":"Only include domains under this price (USD)"},{"name":"sort","in":"query","schema":{"type":"string","enum":["price","tld"],"default":"price"},"description":"Sort results by price or TLD name"},{"name":"source","in":"query","schema":{"type":"string","enum":["all","primary","secondary"],"default":"all"},"description":"Filter results by source: 'primary' (registrar availability only), 'secondary' (Domani marketplace listings only), or 'all' (both)"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}}],"responses":{"200":{"description":"Domain availability and pricing. Single domain (via `q`) returns a flat object. Multiple domains (via `domains`) returns `{ results, total, available }`. With `Accept: text/event-stream`, returns SSE events (`event: result` per domain, `event: done` with summary).","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"},"examples":{"single":{"summary":"Single domain (via ?q=)","value":{"available":true,"domain":"mysite.com","price":10.88,"currency":"USD"}},"multi":{"summary":"Multiple domains (via ?domains=)","value":{"results":[{"available":true,"domain":"myapp.xyz","price":4.04,"currency":"USD"},{"available":true,"domain":"myapp.com","price":10.88,"currency":"USD"},{"available":false,"domain":"myapp.dev","price":15.85,"currency":"USD","for_sale":{"price":2500,"currency":"USD","source":"Sedo","buyable":false,"url":"https://sedo.com/search/details/?domain=myapp.dev"}}],"total":3,"available":2}}}}}},"400":{"description":"Missing or invalid domain format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No query parameter","value":{"error":"Provide 'q' for a single domain or 'domains' for multiple","code":"MISSING_PARAMETER","hint":"Use ?q=example.com or ?domains=example.com,example.dev","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Missing TLD","value":{"error":"Invalid domain format. Use: example.com","code":"INVALID_DOMAIN","hint":"Include TLD, e.g. mysite.com not just mysite","documentation_url":"https://domani.run/llms.txt"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/suggest":{"get":{"operationId":"suggestDomains","summary":"AI-powered domain suggestions with availability","description":"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.","tags":["Domain Search"],"security":[],"x-rateLimit":{"limit":10,"window":"1 minute","scope":"IP address"},"x-codeSamples":[{"lang":"bash","label":"cURL (JSON)","source":"curl \"https://domani.run/api/domains/suggest?prompt=AI+coding+assistant\""},{"lang":"bash","label":"cURL (SSE)","source":"curl \"https://domani.run/api/domains/suggest?prompt=AI+coding+assistant\" -H \"Accept: text/event-stream\""}],"parameters":[{"name":"prompt","in":"query","required":true,"schema":{"type":"string","example":"AI coding assistant","minLength":3},"description":"Project description or keywords to generate domain suggestions from (min 3 characters)"},{"name":"count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":10},"description":"Number of available domains to return (default 10)"},{"name":"exclude","in":"query","required":false,"schema":{"type":"string","example":"codebuddy.dev,aiforge.sh"},"description":"Comma-separated list of domains to exclude from suggestions (e.g. from a previous batch)"},{"name":"tlds","in":"query","required":false,"schema":{"type":"string","example":"com,dev,ai"},"description":"Comma-separated preferred TLDs (without dots). Results will strongly favor these TLDs."},{"name":"style","in":"query","required":false,"schema":{"type":"string","enum":["single","creative","short","brandable","keyword"]},"description":"Name style preference: 'single' (one word), 'creative' (evocative/metaphorical), 'short' (3-6 chars), 'brandable' (invented), 'keyword' (descriptive)."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["japanese","spanish","french","italian","latin","nordic","arabic","sanskrit"]},"description":"Language/cultural inspiration for names. Names will draw from this language's words, aesthetics, and culture."}],"responses":{"200":{"description":"Available domain suggestions with pricing. With `Accept: text/event-stream`, streams SSE events: `suggestion` (each available domain), `checking` (batch being checked), `iteration` (loop round), `done` (summary), `error`.","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"Full domain name with TLD"},"price":{"type":"number","description":"Registration price in USD"},"currency":{"type":"string","description":"Currency code"}},"required":["domain","price","currency"]},"description":"Available domain names with pricing"},"checked":{"type":"integer","description":"Total domains checked"},"iterations":{"type":"integer","description":"Number of LLM rounds"}},"required":["suggestions","checked","iterations"]},"example":{"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}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Prompt must be at least 3 characters","code":"INVALID_PARAMETER","hint":"Provide a longer description","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains":{"get":{"operationId":"listDomains","summary":"List all your registered domains","description":"Returns all domains owned by the authenticated user, ordered by purchase date (newest first). Includes domain name, status, purchase date, and expiration date.","tags":["Domains"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/domains \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"responses":{"200":{"description":"List of registered domains","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/DomainRecord"}}}},"example":{"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}]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/buy":{"post":{"operationId":"buyDomain","summary":"Purchase one or more domains","description":"Purchases one or more domains and registers them immediately. Send `{\"domain\": \"...\"}` for single or `{\"domains\": [\"...\", \"...\"]}` for bulk (max 10).\n\nIf 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%).\n\nBulk purchases process each domain independently - failures don't block other purchases. The response includes `results` (succeeded), `errors` (failed), and `summary` with counts.\n\nAccepts three payment methods:\n\n1. **Card** (default): Requires a card on file via POST /api/billing/setup. Charged per domain.\n2. **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.\n3. **x402 USDC** (atomic): Include a `PAYMENT-SIGNATURE` header with a signed USDC payment on Base.\n\nBulk 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.","tags":["Domains"],"x-rateLimit":{"limit":10,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/domains/buy \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain\": \"mysite.com\"}'"}],"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64-encoded x402 payment payload (USDC on Base). When provided, the domain is paid with USDC instead of a card. x402-compatible clients handle this automatically after receiving a 402 response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","example":"mysite.com","description":"Single domain to purchase (e.g. mysite.com)"},"domains":{"type":"array","items":{"type":"string"},"example":["mysite.com","mysite.dev"],"description":"Array of domains to purchase (max 10, requires card on file)"},"payment_method":{"type":"string","enum":["card","usdc"],"description":"Payment method: 'card' (default) or 'usdc'. When 'usdc', first call returns 402 with payment instructions."},"payment_tx":{"type":"string","description":"Transaction hash of a USDC payment already sent on-chain. Required on the second call of the two-step USDC flow."},"payment_chain":{"type":"string","enum":["base","ethereum"],"description":"Chain the USDC payment was sent on (e.g. 'base' or 'ethereum')."},"years":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Number of years to register (1-10, default 1). Price is multiplied by years."},"ref":{"type":"string","description":"Referral code (optional) - the referrer earns a commission"}}},"examples":{"single":{"summary":"Single domain","value":{"domain":"mysite.com"}},"bulk":{"summary":"Multiple domains","value":{"domains":["mysite.com","mysite.dev","mysite.ai"]}}}}}},"responses":{"201":{"description":"Domain purchased and registered successfully","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["active"]},"expires":{"type":"string","format":"date-time"},"price":{"type":"number"},"currency":{"type":"string"},"years":{"type":"integer","description":"Number of years registered"},"payment_method":{"type":"string","enum":["card","x402","crypto"],"description":"How the domain was paid for"},"payment_tx":{"type":"string","description":"On-chain transaction hash (present for USDC payments)"},"marketplace_purchase":{"type":"boolean","description":"True when the domain was bought from the Domani marketplace (not a fresh registration)"}}},"examples":{"registration":{"summary":"Fresh registration","value":{"domain":"mysite.com","status":"active","expires":"2026-02-18T00:00:00.000Z","price":10.88,"currency":"USD","years":1,"payment_method":"card"}},"marketplace":{"summary":"Marketplace purchase","value":{"domain":"premium.com","status":"active","expires":null,"price":5000,"currency":"USD","years":0,"payment_method":"card","marketplace_purchase":true}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Valid domain is required","code":"INVALID_DOMAIN","hint":"Use format name.tld, e.g. mysite.com","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"402":{"description":"Payment required - includes x402 payment requirements for USDC on Base","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment requirements. x402-compatible clients decode this and auto-retry with a PAYMENT-SIGNATURE header.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Payment required to register mysite.com","code":"PAYMENT_REQUIRED","hint":"Include a PAYMENT-SIGNATURE header with a signed USDC payment on Base, or set up a card via POST /api/billing/setup","documentation_url":"https://domani.run/llms.txt","x402":{"x402Version":2,"resource":{"url":"${APP_URL}/api/domains/buy","description":"Domain registration: mysite.com ($10.88)","mimeType":"application/json"},"accepts":[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"10880000","payTo":"0x...","maxTimeoutSeconds":30}]}}}}},"409":{"description":"Domain is not available for registration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unavailable":{"summary":"Domain is taken","value":{"error":"Domain is not available","code":"DOMAIN_UNAVAILABLE","hint":"Try a different domain or TLD","documentation_url":"https://domani.run/llms.txt"}},"already_registered":{"summary":"Already in our system","value":{"error":"Domain already registered","code":"DOMAIN_UNAVAILABLE","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/dns":{"get":{"operationId":"getDnsRecords","summary":"Get DNS records for a domain you own","description":"Returns all DNS records configured for a domain you own. Includes A, AAAA, CNAME, MX, TXT, NS, and other record types.","tags":["DNS"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/domains/mysite.com/dns \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"DNS records for the domain","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}}},"example":{"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}]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"put":{"operationId":"setDnsRecords","summary":"Set DNS records for a domain you own","description":"Replaces all DNS records for a domain you own. Send the complete set of records - any existing records not included will be removed.","tags":["DNS"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL - point domain to Vercel","source":"curl -X PUT https://domani.run/api/domains/mysite.com/dns \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"records\": [\n    {\"type\": \"A\", \"name\": \"@\", \"value\": \"76.76.21.21\", \"ttl\": 3600},\n    {\"type\": \"CNAME\", \"name\": \"www\", \"value\": \"cname.vercel-dns.com\", \"ttl\": 3600}\n  ]}'"}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}},"required":["records"]},"example":{"records":[{"type":"A","name":"@","value":"76.76.21.21","ttl":3600},{"type":"CNAME","name":"www","value":"cname.vercel-dns.com","ttl":3600}]}}}},"responses":{"200":{"description":"DNS records updated successfully","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"domain":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}}},"example":{"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}]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Records array is required","code":"MISSING_PARAMETER","hint":"Provide a 'records' array in the request body","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/dns/snapshot":{"post":{"operationId":"snapshotDns","summary":"Capture a DNS snapshot","description":"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.","tags":["DNS"],"x-rateLimit":{"limit":10,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/domains/mysite.com/dns/snapshot \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"extra_subdomains":{"type":"array","items":{"type":"string"},"description":"Additional subdomains to include in the snapshot"}}},"example":{"extra_subdomains":["api","cdn","staging"]}}}},"responses":{"200":{"description":"DNS snapshot captured","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"subdomains":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"capturedAt":{"type":"string","format":"date-time"}}},"example":{"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"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/dns/restore":{"post":{"operationId":"restoreDns","summary":"Restore DNS from a snapshot","description":"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).","tags":["DNS"],"x-rateLimit":{"limit":10,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL - restore from server backup","source":"curl -X POST https://domani.run/api/domains/mysite.com/dns/restore \\\n  -H \"Authorization: Bearer domani_sk_xxx\""},{"lang":"bash","label":"cURL - restore from local file","source":"curl -X POST https://domani.run/api/domains/mysite.com/dns/restore \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"snapshot\": '\"$(cat mysite.com.dns.json)\"'}'"}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"snapshot":{"type":"object","description":"A DNS snapshot object (as returned by the snapshot endpoint). If omitted, the stored server-side backup is used.","properties":{"domain":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"subdomains":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"capturedAt":{"type":"string","format":"date-time"}}}}}}}},"responses":{"200":{"description":"DNS restored from snapshot","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"applied":{"type":"integer","description":"Number of records created"},"skipped":{"type":"integer","description":"Number of records already present"},"recordCount":{"type":"integer","description":"Total records in the snapshot"},"errors":{"type":"array","items":{"type":"string"}}}},"example":{"domain":"mysite.com","applied":5,"skipped":2,"recordCount":7,"errors":[]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No snapshot provided and no stored backup found","code":"NO_SNAPSHOT","hint":"Capture a snapshot first with POST /api/domains/:domain/dns/snapshot","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"409":{"description":"Domain not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain is not active","code":"DOMAIN_NOT_ACTIVE","hint":"Domain must be active to restore DNS"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/nameservers":{"get":{"operationId":"getNameservers","summary":"Get nameservers for a domain","description":"Returns the authoritative nameservers configured for a domain you own. If empty, DNS operations (parking, email, connect) will fail until nameservers are assigned.","tags":["DNS"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/domains/mysite.com/nameservers \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Nameservers for the domain","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"nameservers":{"type":"array","items":{"type":"string"}},"default_nameservers":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Registrar default nameservers (null if unknown)"},"hint":{"type":"string"}}},"example":{"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."}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"put":{"operationId":"setNameservers","summary":"Set nameservers for a domain","description":"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).","tags":["DNS"],"x-rateLimit":{"limit":30,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X PUT https://domani.run/api/domains/mysite.com/nameservers \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"nameservers\": [\"ns1.systemdns.com\", \"ns2.systemdns.com\", \"ns3.systemdns.com\"]}'"}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nameservers":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":13,"description":"Nameserver hostnames (2–13 required)"}},"required":["nameservers"]},"example":{"nameservers":["ns1.systemdns.com","ns2.systemdns.com","ns3.systemdns.com"]}}}},"responses":{"200":{"description":"Nameservers updated successfully","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"domain":{"type":"string"},"nameservers":{"type":"array","items":{"type":"string"}},"hint":{"type":"string"}}},"example":{"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."}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"At least 2 nameservers required","code":"VALIDATION_ERROR","hint":"Provide 2–13 valid nameserver hostnames","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/connect":{"post":{"operationId":"connectDomain","summary":"Connect a domain to a hosting or email provider","description":"Connects a domain to a hosting or email provider by auto-detecting the provider from a target URL or accepting an explicit provider name.\n\nFor 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`).\n\nSupported hosting providers: vercel, netlify, cloudflare-pages, github-pages, railway, fly.\nSupported email providers: google-workspace, fastmail, proton.\n\nUse `GET /api/domains/{domain}/connect` to list all available providers and methods.","tags":["Connect"],"x-rateLimit":{"limit":30,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL - auto-detect from target","source":"curl -X POST https://domani.run/api/domains/mysite.com/connect \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"target\": \"my-app.vercel.app\"}'"},{"lang":"bash","label":"cURL - explicit provider","source":"curl -X POST https://domani.run/api/domains/mysite.com/connect \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"provider\": \"google-workspace\"}'"}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","description":"Target URL for auto-detection (e.g. my-app.vercel.app)","example":"my-app.vercel.app"},"provider":{"type":"string","description":"Explicit provider name (e.g. vercel, google-workspace)","example":"vercel"},"method":{"type":"string","description":"Connection method if provider has multiple (e.g. cname-only)"}}},"examples":{"autoDetect":{"summary":"Auto-detect from target","value":{"target":"my-app.vercel.app"}},"explicit":{"summary":"Explicit provider","value":{"provider":"google-workspace"}},"withMethod":{"summary":"Provider with specific method","value":{"provider":"netlify","method":"cname-only"}}}}}},"responses":{"200":{"description":"Domain connected or DNS instructions returned","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"provider":{"type":"string"},"category":{"type":"string","enum":["hosting","email"]},"method":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"docs":{"type":"string","format":"uri"},"status":{"type":"string","enum":["dns_set","manual_setup_required"],"description":"dns_set = records written automatically. manual_setup_required = imported domain, add records at your registrar."},"hint":{"type":"string"},"next_steps":{"type":"array","items":{"type":"string"},"description":"Provider-specific actions to complete after DNS records are set"}}},"examples":{"managed":{"summary":"Managed domain (DNS set automatically)","value":{"domain":"mysite.com","provider":"vercel","category":"hosting","method":"recommended","records":[{"record":{"type":"A","name":"@","value":"76.76.21.21","ttl":3600},"status":"created"},{"record":{"type":"CNAME","name":"www","value":"cname.vercel-dns.com","ttl":3600},"status":"created"}],"docs":"https://vercel.com/docs/projects/domains","status":"dns_set","hint":"Add mysite.com to your Vercel project: run `npx vercel domains add mysite.com` in your project directory, or add it in Project Settings > Domains on vercel.com","next_steps":["Add mysite.com to your Vercel project: run `npx vercel domains add mysite.com` in your project directory, or add it in Project Settings > Domains on vercel.com","DNS propagation may take up to 48 hours. Verify with POST /api/domains/mysite.com/verify"]}},"imported":{"summary":"Imported domain (manual DNS setup required)","value":{"domain":"mysite.com","provider":"vercel","category":"hosting","method":"recommended","records":[{"record":{"type":"A","name":"@","value":"76.76.21.21","ttl":3600},"status":"pending"},{"record":{"type":"CNAME","name":"www","value":"cname.vercel-dns.com","ttl":3600},"status":"pending"}],"docs":"https://vercel.com/docs/projects/domains","status":"manual_setup_required","hint":"Add the DNS records above at your current registrar (Namecheap, GoDaddy, Cloudflare, etc.)","next_steps":["Add the DNS records above at your current registrar (Namecheap, GoDaddy, Cloudflare, etc.)","Add mysite.com to your Vercel project: run `npx vercel domains add mysite.com` in your project directory, or add it in Project Settings > Domains on vercel.com","DNS propagation may take up to 48 hours. Verify with POST /api/domains/mysite.com/verify"]}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Either 'target' or 'provider' is required","code":"MISSING_PARAMETER","hint":"Pass { target: 'my-app.vercel.app' } or { provider: 'vercel' }","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"get":{"operationId":"listConnectProviders","summary":"List available providers for connecting a domain","description":"Returns all supported hosting and email providers with their connection methods. Use this to discover what providers are available before calling POST.","tags":["Connect"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Available providers grouped by category","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"providers":{"type":"object","properties":{"hosting":{"type":"array","items":{"type":"object","description":"Provider with name, category, patterns, requires_target, notes, methods, docs"}},"email":{"type":"array","items":{"type":"object","description":"Provider with name, category, patterns, requires_target, notes, methods, docs"}}}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/status":{"get":{"operationId":"getDomainStatus","summary":"Check domain health: DNS, SSL, email, expiry","description":"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.","tags":["Status"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/domains/mysite.com/status \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Domain health status","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string"},"expires":{"type":"string","format":"date-time"},"days_until_expiry":{"type":"integer"},"dns":{"type":"object","properties":{"propagated":{"type":"boolean"},"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"cname":{"type":"array","items":{"type":"string"}},"mx":{"type":"array","items":{"type":"string"}},"txt":{"type":"array","items":{"type":"string"}},"ns":{"type":"array","items":{"type":"string"}},"registrar_records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}}},"ssl":{"type":"object","properties":{"active":{"type":"boolean"}}},"email":{"type":"object","properties":{"configured":{"type":"boolean"},"mx":{"type":"array","items":{"type":"string"}}}}}},"example":{"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":[]}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/email/check":{"get":{"operationId":"checkEmail","summary":"Check email DNS health (MX, SPF, DMARC, DKIM)","description":"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).","tags":["Email"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/domains/mysite.com/email/check \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Email DNS health report","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"provider":{"type":"string","nullable":true,"description":"Auto-detected email provider (google-workspace, proton, fastmail) or null"},"mx":{"type":"object","properties":{"configured":{"type":"boolean"},"records":{"type":"array","items":{"type":"string"}}}},"spf":{"type":"object","properties":{"configured":{"type":"boolean"},"value":{"type":"string","nullable":true}}},"dmarc":{"type":"object","properties":{"configured":{"type":"boolean"},"value":{"type":"string","nullable":true}}},"dkim":{"type":"object","properties":{"configured":{"type":"boolean"},"selectors":{"type":"array","items":{"type":"string"}}}}}},"example":{"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"]}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/verify":{"post":{"operationId":"verifyConnection","summary":"Verify that a provider connection is working","description":"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.","tags":["Connect"],"x-rateLimit":{"limit":30,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/domains/mysite.com/verify \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"target\": \"my-app.vercel.app\"}'"}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","description":"Target for auto-detection"},"provider":{"type":"string","description":"Provider name"},"method":{"type":"string","description":"Method name"}}}}}},"responses":{"200":{"description":"Verification result","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"provider":{"type":"string"},"method":{"type":"string"},"verified":{"type":"boolean"},"message":{"type":"string"},"hint":{"type":"string"},"next_steps":{"type":"array","items":{"type":"string"},"description":"Provider-specific troubleshooting steps (only when verified is false)"}}},"examples":{"verified":{"summary":"Connection verified","value":{"domain":"mysite.com","provider":"vercel","method":"recommended","verified":true,"message":"DNS records verified - connection is active"}},"pending":{"summary":"DNS not yet propagated","value":{"domain":"mysite.com","provider":"vercel","method":"recommended","verified":false,"message":"DNS records not yet propagated","hint":"Ensure you completed the provider-side setup: Add mysite.com to your Vercel project: run `npx vercel domains add mysite.com` in your project directory, or add it in Project Settings > Domains on vercel.com","next_steps":["Ensure you completed the provider-side setup: Add mysite.com to your Vercel project: run `npx vercel domains add mysite.com` in your project directory, or add it in Project Settings > Domains on vercel.com","DNS propagation can take up to 48 hours. Try again later."]}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Either 'target' or 'provider' is required","code":"MISSING_PARAMETER","hint":"Pass the same target/provider you used when connecting","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/verify-service":{"post":{"operationId":"verifyService","summary":"Add DNS records to verify domain ownership for a third-party service","description":"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.\n\nRecords are merged with existing DNS - existing records are preserved.","tags":["Verify Service"],"x-rateLimit":{"limit":30,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL - Stripe verification","source":"curl -X POST https://domani.run/api/domains/mysite.com/verify-service \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"service\": \"stripe\", \"token\": \"abc123def456\"}'"},{"lang":"bash","label":"cURL - Google Search Console","source":"curl -X POST https://domani.run/api/domains/mysite.com/verify-service \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"service\": \"google-search-console\", \"token\": \"abcdef123456\"}'"}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service","token"],"properties":{"service":{"type":"string","description":"Service name (e.g. stripe, google-search-console, aws-ses, postmark, resend, facebook, hubspot, microsoft-365)","example":"stripe"},"token":{"type":"string","description":"Verification token provided by the service","example":"abc123def456"}}},"examples":{"stripe":{"summary":"Stripe","value":{"service":"stripe","token":"abc123def456"}},"google":{"summary":"Google Search Console","value":{"service":"google-search-console","token":"abcdef123456"}},"aws":{"summary":"AWS SES","value":{"service":"aws-ses","token":"EXAMPLE+abc123"}},"generic":{"summary":"Generic (any service)","value":{"service":"my-saas","token":"verify-my-domain-xyz"}}}}}},"responses":{"200":{"description":"Verification records added","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"service":{"type":"string"},"service_display_name":{"type":"string"},"known_service":{"type":"boolean"},"records_added":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"total_records":{"type":"integer"},"docs":{"type":"string","format":"uri","nullable":true},"hint":{"type":"string"}}},"example":{"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."}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Missing 'service' parameter","code":"MISSING_PARAMETER","hint":"Send { service: 'stripe', token: 'your-token' }","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"get":{"operationId":"listVerifyServices","summary":"List supported services for domain verification","description":"Returns all known services with their names, descriptions, and documentation URLs. Unknown services fall back to a generic TXT record.","tags":["Verify Service"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Available services","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"services":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"docs":{"type":"string","format":"uri"}}}},"hint":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}":{"get":{"operationId":"getDomainInfo","summary":"Get detailed information about a domain you own","description":"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.","tags":["Domains"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/domains/mysite.com \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Domain details","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDetail"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/settings":{"put":{"operationId":"updateDomainSettings","summary":"Update domain settings","description":"Update settings for a domain you own. Supports `auto_renew`, `whois_privacy`, and `security_lock`. At least one field must be provided.","tags":["Domains"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL - Disable auto-renew","source":"curl -X PUT https://domani.run/api/domains/mysite.com/settings \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"auto_renew\": false}'"},{"lang":"bash","label":"cURL - Enable auto-renew","source":"curl -X PUT https://domani.run/api/domains/mysite.com/settings \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"auto_renew\": true}'"},{"lang":"bash","label":"cURL - Enable WHOIS privacy","source":"curl -X PUT https://domani.run/api/domains/mysite.com/settings \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"whois_privacy\": true}'"}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"auto_renew":{"type":"boolean","description":"Whether to enable auto-renew for this domain"},"whois_privacy":{"type":"boolean","description":"Whether to enable WHOIS privacy protection"},"security_lock":{"type":"boolean","description":"Whether to lock the domain against transfers"}}},"examples":{"disable":{"summary":"Disable auto-renew","value":{"auto_renew":false}},"enable":{"summary":"Enable auto-renew","value":{"auto_renew":true}},"privacy":{"summary":"Enable WHOIS privacy","value":{"whois_privacy":true}},"unlock":{"summary":"Unlock for transfer","value":{"security_lock":false}}}}}},"responses":{"200":{"description":"Settings updated","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"auto_renew":{"type":"boolean"},"whois_privacy":{"type":"boolean"},"security_lock":{"type":"boolean"},"hint":{"type":"string"}},"required":["domain","hint"]},"examples":{"disabled":{"summary":"Auto-renew disabled","value":{"domain":"mysite.com","auto_renew":false,"hint":"Auto-renew is now disabled. Remember to renew manually before the domain expires."}},"enabled":{"summary":"Auto-renew enabled","value":{"domain":"mysite.com","auto_renew":true,"hint":"Auto-renew is now enabled. The domain will be renewed automatically before expiry."}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"auto_renew must be a boolean","code":"INVALID_PARAMETER","hint":"Send { \"auto_renew\": true } or { \"auto_renew\": false }","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/parking":{"put":{"operationId":"updateParking","summary":"Update parking settings","description":"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.","tags":["Domains"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"Domain name"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether to enable the parking page"},"listing_price":{"type":"number","nullable":true,"description":"Sale price in USD, or null to remove listing"}}},"examples":{"enable":{"summary":"Enable parking","value":{"enabled":true}},"disable":{"summary":"Disable parking","value":{"enabled":false}},"list":{"summary":"List for sale","value":{"listing_price":499.99}},"unlist":{"summary":"Remove listing","value":{"listing_price":null}}}}}},"responses":{"200":{"description":"Parking settings updated","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"parking_enabled":{"type":"boolean"},"listing_price":{"type":"number","nullable":true},"hint":{"type":"string"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No parking settings provided","code":"INVALID_PARAMETER","hint":"Send { \"enabled\": true/false, \"listing_price\": 499.99 }","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/notifications":{"get":{"operationId":"listNotifications","summary":"List notifications","description":"List your in-app notifications with cursor-based pagination. Includes deal events, listing updates, and system alerts.\n\nRequires `notifications:read` scope.","tags":["Notifications"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Max notifications to return"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor for pagination (from previous response's next_cursor)"}],"responses":{"200":{"description":"List of notifications","content":{"application/json":{"schema":{"type":"object","properties":{"notifications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"action_url":{"type":"string","nullable":true},"read":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/notifications/count":{"get":{"operationId":"getUnreadCount","summary":"Get unread notification count","description":"Lightweight endpoint for polling unread notification count.\n\nRequires `notifications:read` scope.","tags":["Notifications"],"x-rateLimit":{"limit":120,"window":"1 minute"},"responses":{"200":{"description":"Unread count","content":{"application/json":{"schema":{"type":"object","properties":{"unread_count":{"type":"integer"}}},"example":{"unread_count":3}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/notifications/{id}":{"patch":{"operationId":"markNotificationRead","summary":"Mark notification as read","description":"Mark a single notification as read.\n\nRequires `notifications:read` scope.","tags":["Notifications"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Notification ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"read":{"type":"boolean","description":"Set to true to mark as read"}},"required":["read"]}}}},"responses":{"200":{"description":"Notification updated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Notification not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Notification not found","code":"NOT_FOUND","hint":"Verify the notification exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/notifications/read-all":{"post":{"operationId":"markAllNotificationsRead","summary":"Mark all notifications as read","description":"Mark all unread notifications as read.\n\nRequires `notifications:read` scope.","tags":["Notifications"],"x-rateLimit":{"limit":10,"window":"1 minute"},"responses":{"200":{"description":"All notifications marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"integer","description":"Number of notifications marked as read"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/notifications/preferences":{"get":{"operationId":"getNotificationPreferences","summary":"Get notification preferences","description":"Returns the user's notification preferences for each category and channel (in_app, email). Missing preferences default to enabled.\n\nRequires `notifications:read` scope.","tags":["Notifications"],"x-rateLimit":{"limit":30,"window":"1 minute"},"responses":{"200":{"description":"Notification preferences","content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","description":"Preference category","enum":["domains","transfers","marketplace","email","inquiries"]},"label":{"type":"string"},"description":{"type":"string"},"channel":{"type":"string","enum":["in_app","email"]},"enabled":{"type":"boolean"}}}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"put":{"operationId":"updateNotificationPreferences","summary":"Update notification preferences","description":"Update notification preferences for specific categories and channels.\n\nRequires `notifications:read` scope.","tags":["Notifications"],"x-rateLimit":{"limit":10,"window":"1 minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["preferences"],"properties":{"preferences":{"type":"array","items":{"type":"object","required":["category","channel","enabled"],"properties":{"category":{"type":"string","enum":["domains","transfers","marketplace","email","inquiries"]},"channel":{"type":"string","enum":["in_app","email"]},"enabled":{"type":"boolean"}}}}}}}}},"responses":{"200":{"description":"Preferences updated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/analytics":{"get":{"operationId":"getParkingAnalytics","summary":"Get parking analytics","description":"Get visitor analytics for a parked domain - page views, inquiries, conversion rate, 30-day daily breakdown, and recent inquiries.","tags":["Domains"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"Domain name"}],"responses":{"200":{"description":"Parking analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"views_7d":{"type":"integer","description":"Total page views in the last 7 days"},"views_30d":{"type":"integer","description":"Total page views in the last 30 days"},"inquiries_30d":{"type":"integer","description":"Total inquiries in the last 30 days"},"conversion_rate":{"type":"number","description":"Inquiry-to-view ratio as percentage"},"daily_views":{"type":"array","description":"Daily view counts for the last 30 days","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"views":{"type":"integer"}}}},"recent_inquiries":{"type":"array","description":"5 most recent inquiries","items":{"type":"object","properties":{"email":{"type":"string"},"offer":{"type":"number","nullable":true},"date":{"type":"string","format":"date-time"}}}},"hint":{"type":"string"}}},"example":{"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)."}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/auth-code":{"get":{"operationId":"getAuthCode","summary":"Get EPP auth code","description":"Get the EPP/auth code needed to transfer a domain to another registrar. Automatically unlocks the domain if it's locked.","tags":["Domains"],"x-rateLimit":{"limit":10,"window":"1 minute"},"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Auth code retrieved","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"auth_code":{"type":"string","description":"EPP auth code to give to the new registrar"},"was_unlocked":{"type":"boolean","description":"Whether the domain was auto-unlocked"},"hint":{"type":"string"},"next_steps":{"type":"array","items":{"type":"string"}}},"required":["domain","auth_code","was_unlocked","hint","next_steps"]},"examples":{"unlocked":{"summary":"Auth code with auto-unlock","value":{"domain":"mysite.com","auth_code":"aBc123XyZ","was_unlocked":true,"hint":"Auth code retrieved. Domain was automatically unlocked to allow transfer.","next_steps":["Give this auth code to your new registrar to initiate the transfer.","The transfer typically takes 5-7 days to complete.","Use get_transfer_away to monitor the transfer status."]}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/transfer-away":{"get":{"operationId":"getTransferAway","summary":"Get outbound transfer status","description":"Check the status of an outbound domain transfer. Use after getting an auth code and initiating the transfer at the new registrar.","tags":["Domains"],"x-rateLimit":{"limit":30,"window":"1 minute"},"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Transfer status retrieved","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["none","pending","approved","completed","rejected","expired"]},"gaining_registrar":{"type":"string"},"request_date":{"type":"string","format":"date-time"},"hint":{"type":"string"}},"required":["domain","status","hint"]},"examples":{"none":{"summary":"No transfer in progress","value":{"domain":"mysite.com","status":"none","hint":"No outbound transfer in progress."}},"pending":{"summary":"Transfer pending","value":{"domain":"mysite.com","status":"pending","gaining_registrar":"Cloudflare","request_date":"2026-02-20T10:00:00Z","hint":"Transfer is pending approval. The gaining registrar has initiated the transfer."}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/transfer-status":{"get":{"operationId":"checkTransferStatus","summary":"Check inbound transfer status","description":"Check the status of an inbound domain transfer. Returns detailed status with actionable hints. Use after initiating a transfer with POST /api/domains/transfer.","tags":["Domains"],"x-rateLimit":{"limit":30,"window":"1 minute"},"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"responses":{"200":{"description":"Transfer status retrieved","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["pending_owner","pending_admin","pending_registry","completed","cancelled","unknown"]},"timestamp":{"type":"string","description":"Timestamp of last status update"},"hint":{"type":"string","description":"Actionable guidance based on the current status"}},"required":["domain","status","hint"]},"examples":{"pending_owner":{"summary":"Awaiting owner approval","value":{"domain":"mysite.com","status":"pending_owner","hint":"Transfer is awaiting approval from the domain owner (admin contact). Check email for confirmation link."}},"completed":{"summary":"Transfer completed","value":{"domain":"mysite.com","status":"completed","hint":"Transfer completed successfully. The domain is now in your account."}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/import":{"post":{"operationId":"importDomain","summary":"Import an external domain","description":"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.","tags":["Domains"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"mysite.com","description":"Domain to import"}}}}}},"responses":{"200":{"description":"Verification instructions","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","example":"pending_verification"},"token":{"type":"string"},"txt_record":{"type":"object","properties":{"type":{"type":"string","example":"TXT"},"name":{"type":"string","example":"@"},"value":{"type":"string","example":"domani-verify=abc123..."}}},"hint":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"409":{"description":"Domain already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain already registered in our system","code":"DOMAIN_EXISTS","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/import/verify":{"post":{"operationId":"verifyImport","summary":"Verify and complete domain import","description":"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.","tags":["Domains"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"mysite.com","description":"Domain to verify"}}}}}},"responses":{"201":{"description":"Domain imported successfully","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","example":"active"},"expires":{"type":"string","format":"date-time"},"registrar":{"type":"string","example":"external"},"payment_method":{"type":"string","example":"import"},"hint":{"type":"string"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"TXT record not found","code":"VERIFICATION_FAILED","hint":"Add TXT record and wait for DNS propagation","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"409":{"description":"Domain already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain already registered in our system","code":"DOMAIN_EXISTS","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/transfer-check":{"get":{"operationId":"checkTransferEligibility","summary":"Pre-check transfer eligibility","description":"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.","tags":["Domains"],"x-rateLimit":{"limit":30,"window":"1 minute"},"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"description":"Domain to check, e.g. mysite.com"}],"responses":{"200":{"description":"Eligibility check result","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"tld":{"type":"string"},"eligible":{"type":"boolean"},"price":{"type":"number","nullable":true,"description":"Transfer price in USD (null if TLD unsupported)"},"currency":{"type":"string"},"reason":{"type":"string","description":"Human-readable reason if not eligible"},"code":{"type":"string","enum":["UNSUPPORTED_TLD","NOT_AVAILABLE","ALREADY_REGISTERED","TRANSFER_NOT_ELIGIBLE"]},"eligible_at":{"type":"string","format":"date","description":"ISO date when domain becomes eligible (ICANN waiting period)"},"hint":{"type":"string"}},"required":["domain","tld","eligible","price","currency"]},"examples":{"eligible":{"summary":"Domain is eligible","value":{"domain":"mysite.com","tld":"com","eligible":true,"price":13.08,"currency":"USD","hint":"Transfer includes 1 year of renewal. Price: $13.08 USD."}},"unsupported":{"summary":"TLD not supported","value":{"domain":"mysite.so","tld":"so","eligible":false,"price":null,"currency":"USD","reason":"TLD .so is not available for transfer.","code":"UNSUPPORTED_TLD","hint":"Use GET /api/tlds to see supported TLDs."}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"domain query parameter is required","code":"INVALID_PARAMETER","hint":"Pass ?domain=example.com","documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/transfer-watch":{"post":{"operationId":"watchTransfer","summary":"Watch a domain for transfer eligibility","description":"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.","tags":["Domains"],"x-rateLimit":{"limit":30,"window":"1 minute"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Domain to watch, e.g. mysite.com"}}},"examples":{"watch":{"summary":"Watch a domain","value":{"domain":"mysite.com"}}}}}},"responses":{"200":{"description":"Watch result","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"eligible":{"type":"boolean","description":"Whether the domain is currently eligible for transfer"},"eligible_at":{"type":"string","format":"date","description":"ISO date when domain becomes eligible (if not yet eligible)"},"hint":{"type":"string","description":"Actionable guidance"},"watching":{"type":"boolean","description":"Whether a notification has been set up"}},"required":["domain","eligible","watching"]},"examples":{"watching":{"summary":"Domain not yet eligible, watching","value":{"domain":"mysite.com","eligible":false,"eligible_at":"2026-04-16","hint":"Domain was registered on 2026-02-15. ICANN requires a 60-day wait. Transferable from 2026-04-16. We'll notify you (email + webhook) when it's ready.","watching":true}},"alreadyEligible":{"summary":"Domain already eligible","value":{"domain":"mysite.com","eligible":true,"hint":"Domain is already eligible for transfer. You can initiate a transfer now with POST /api/domains/transfer.","watching":false}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"domain is required","code":"INVALID_PARAMETER","hint":"Send { \"domain\": \"example.com\" }","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/transfer":{"post":{"operationId":"transferDomain","summary":"Transfer domain from another provider","description":"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).","tags":["Domains"],"x-rateLimit":{"limit":5,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/domains/transfer \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain\": \"mysite.com\", \"auth_code\": \"EPP-AUTH-CODE\"}'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain","auth_code"],"properties":{"domain":{"type":"string","description":"Domain to transfer, e.g. mysite.com"},"auth_code":{"type":"string","description":"Authorization/EPP code from the current provider"},"payment_method":{"type":"string","enum":["card","usdc"],"description":"Payment method: 'card' (default) or 'usdc'."},"payment_tx":{"type":"string","description":"Transaction hash of a USDC payment already sent on-chain."},"payment_chain":{"type":"string","enum":["base","ethereum"],"description":"Chain the USDC payment was sent on."},"extra_subdomains":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"Additional subdomains to include in the pre-transfer DNS snapshot. We auto-discover subdomains via CT logs, SPF, MX/DKIM inference, and a common wordlist - use this for any custom subdomains we might miss."}}},"examples":{"transfer":{"summary":"Transfer a domain","value":{"domain":"mysite.com","auth_code":"aBc123XyZ"}}}}}},"responses":{"202":{"description":"Transfer initiated","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["pending","active"]},"expires":{"type":"string","format":"date-time"},"price":{"type":"number"},"currency":{"type":"string"},"payment_method":{"type":"string"},"payment_tx":{"type":"string"},"auto_renew":{"type":"boolean"},"hint":{"type":"string"},"dns_snapshot":{"type":"object","description":"Summary of DNS records captured before the transfer. Records are auto-restored when the transfer completes.","properties":{"record_count":{"type":"integer","description":"Total DNS records captured"},"subdomain_count":{"type":"integer","description":"Number of subdomains discovered"}}}},"required":["domain","status","expires","price","currency","payment_method","hint"]},"examples":{"pending":{"summary":"Transfer pending","value":{"domain":"mysite.com","status":"pending","expires":"2027-02-18T00:00:00.000Z","price":13.99,"currency":"USD","payment_method":"card","hint":"Transfer initiated. It may take up to 5 days to complete. Check status with GET /api/domains/{domain}"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Valid domain and auth_code are required","code":"INVALID_DOMAIN","hint":"Provide domain and auth_code in the request body","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Payment required","code":"PAYMENT_REQUIRED","hint":"Add a card via POST /api/billing/setup, or pay with USDC on Base (x402)","documentation_url":"https://domani.run/llms.txt"}}}},"409":{"description":"Domain already registered in our system","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain already registered in our system","code":"DOMAIN_EXISTS","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/renew":{"post":{"operationId":"renewDomain","summary":"Renew a domain","description":"Renew a domain you own for additional years (1-10). Payment is charged upfront. The new expiry date is returned in the response.","tags":["Domains"],"x-rateLimit":{"limit":10,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL - Renew 1 year","source":"curl -X POST https://domani.run/api/domains/mysite.com/renew \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"years\": 1}'"},{"lang":"bash","label":"cURL - Renew 3 years","source":"curl -X POST https://domani.run/api/domains/mysite.com/renew \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"years\": 3}'"}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mysite.com"},"description":"Domain name you own"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"years":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Number of years to renew (default 1)"},"payment_method":{"type":"string","enum":["card","usdc"],"description":"Payment method: 'card' (default) or 'usdc'."},"payment_tx":{"type":"string","description":"Transaction hash of a USDC payment already sent on-chain."},"payment_chain":{"type":"string","enum":["base","ethereum"],"description":"Chain the USDC payment was sent on."}}},"examples":{"one_year":{"summary":"Renew 1 year","value":{"years":1}},"three_years":{"summary":"Renew 3 years","value":{"years":3}}}}}},"responses":{"200":{"description":"Domain renewed","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"renewed_years":{"type":"integer"},"new_expiry":{"type":"string","format":"date-time"},"price":{"type":"number"},"currency":{"type":"string"},"payment_method":{"type":"string"},"payment_tx":{"type":"string"}},"required":["domain","renewed_years","new_expiry","price","currency","payment_method"]},"examples":{"renewed":{"summary":"Domain renewed for 2 years","value":{"domain":"mysite.com","renewed_years":2,"new_expiry":"2029-02-18T00:00:00.000Z","price":27.98,"currency":"USD","payment_method":"card"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"years must be an integer between 1 and 10","code":"INVALID_PARAMETER","hint":"Send { \"years\": 1 } (default) up to { \"years\": 10 }","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Payment required","code":"PAYMENT_REQUIRED","hint":"Add a card via POST /api/billing/setup, or pay with USDC on Base (x402)","documentation_url":"https://domani.run/llms.txt"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Domain not found","code":"NOT_FOUND","hint":"Verify the domain exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/whois":{"get":{"operationId":"whoisLookup","summary":"Look up domain registration data via RDAP","description":"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.\n\nRDAP 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).","tags":["Discovery"],"security":[],"x-rateLimit":{"limit":10,"window":"1 minute","scope":"IP address (unauthenticated), 30/min per user (authenticated)"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl \"https://domani.run/api/domains/whois?q=google.com\""}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","example":"google.com"},"description":"Domain to look up (e.g. example.com)"}],"responses":{"200":{"description":"Domain registration data","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","example":"google.com"},"registered":{"type":"boolean","description":"Whether the domain is currently registered"},"registrar":{"type":"string","nullable":true,"example":"MarkMonitor Inc.","description":"Current registrar name"},"registrar_url":{"type":"string","nullable":true,"description":"Registrar website URL"},"registrar_iana_id":{"type":"string","nullable":true,"description":"Registrar IANA ID (from RDAP publicIds)"},"created":{"type":"string","nullable":true,"example":"1997-09-15","description":"Registration date (YYYY-MM-DD)"},"expires":{"type":"string","nullable":true,"example":"2028-09-14","description":"Expiration date (YYYY-MM-DD)"},"updated":{"type":"string","nullable":true,"example":"2019-09-09","description":"Last updated date (YYYY-MM-DD)"},"days_until_expiry":{"type":"integer","nullable":true,"example":939,"description":"Days until expiry (null if not registered)"},"status":{"type":"array","items":{"type":"string"},"example":["clientdeleteprohibited","clienttransferprohibited","clientupdateprohibited"],"description":"EPP status codes"},"nameservers":{"type":"array","items":{"type":"string"},"example":["ns1.google.com","ns2.google.com"],"description":"Authoritative nameservers"},"dnssec":{"type":"boolean","description":"Whether DNSSEC is enabled"},"redacted":{"type":"boolean","description":"Whether WHOIS/RDAP data is redacted for privacy (GDPR)"},"contacts":{"type":"object","description":"Contact information by role (null when no data available, fields may be null when redacted)","properties":{"registrant":{"oneOf":[{"$ref":"#/components/schemas/Contact"},{"type":"null"}],"description":"Domain owner/registrant"},"admin":{"oneOf":[{"$ref":"#/components/schemas/Contact"},{"type":"null"}],"description":"Administrative contact"},"tech":{"oneOf":[{"$ref":"#/components/schemas/Contact"},{"type":"null"}],"description":"Technical contact"},"billing":{"oneOf":[{"$ref":"#/components/schemas/Contact"},{"type":"null"}],"description":"Billing contact"},"abuse":{"oneOf":[{"$ref":"#/components/schemas/Contact"},{"type":"null"}],"description":"Abuse contact (email + phone)"}},"required":["registrant","admin","tech","billing","abuse"]}},"required":["domain","registered","registrar","registrar_url","registrar_iana_id","created","expires","updated","days_until_expiry","status","nameservers","dnssec","redacted","contacts"]},"examples":{"registered":{"summary":"Registered domain","value":{"domain":"google.com","registered":true,"registrar":"MarkMonitor Inc.","registrar_url":"http://www.markmonitor.com","registrar_iana_id":"292","created":"1997-09-15","expires":"2028-09-14","updated":"2019-09-09","days_until_expiry":939,"status":["clientdeleteprohibited","clienttransferprohibited","clientupdateprohibited","serverdeleteprohibited","servertransferprohibited","serverupdateprohibited"],"nameservers":["ns1.google.com","ns2.google.com","ns3.google.com","ns4.google.com"],"dnssec":false,"redacted":true,"contacts":{"registrant":{"name":"REDACTED FOR PRIVACY","organization":"Google LLC","email":"REDACTED FOR PRIVACY","phone":"REDACTED FOR PRIVACY","fax":null,"street":"REDACTED FOR PRIVACY","city":"REDACTED FOR PRIVACY","state":"CA","postal_code":"REDACTED FOR PRIVACY","country":"US"},"admin":null,"tech":null,"billing":null,"abuse":{"name":null,"organization":null,"email":"abusecomplaints@markmonitor.com","phone":"+1.2086851750","fax":null,"street":null,"city":null,"state":null,"postal_code":null,"country":null}}}},"unregistered":{"summary":"Unregistered domain","value":{"domain":"this-domain-is-not-registered.com","registered":false,"registrar":null,"registrar_url":null,"registrar_iana_id":null,"created":null,"expires":null,"updated":null,"days_until_expiry":null,"status":[],"nameservers":[],"dnssec":false,"redacted":false,"contacts":{"registrant":null,"admin":null,"tech":null,"billing":null,"abuse":null}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid domain format","code":"INVALID_DOMAIN","hint":"Domain must be like example.com","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/domains/{domain}/og":{"get":{"operationId":"getDomainOg","summary":"Get website preview metadata for a domain","description":"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.\n\n**Public endpoint** - no authentication required.","tags":["Discovery"],"security":[],"x-rateLimit":{"limit":30,"window":"1 minute","scope":"IP address"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl \"https://domani.run/api/domains/google.com/og\""}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"google.com"},"description":"Domain to fetch metadata for (e.g. google.com)"}],"responses":{"200":{"description":"OG metadata","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","nullable":true,"example":"Google","description":"Page title (og:title > twitter:title > <title>)"},"description":{"type":"string","nullable":true,"example":"Search the world's information","description":"Page description (og:description > meta description)"},"image":{"type":"string","nullable":true,"description":"OG image URL (absolute)"},"favicon":{"type":"string","nullable":true,"example":"https://google.com/favicon.ico","description":"Favicon URL (absolute)"}},"required":["title","description","image","favicon"]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid domain format","code":"INVALID_DOMAIN","hint":"Domain must include a TLD","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/domains/dns-check":{"get":{"operationId":"dnsCheck","summary":"Fast DNS-based domain existence check","description":"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.","tags":["Domain Search"],"security":[],"x-rateLimit":{"limit":30,"window":"1 minute","scope":"IP address"},"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string"},"description":"Domain name without TLD, e.g. 'myapp'"},{"name":"tlds","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated TLDs to check, e.g. 'com,dev,ai,io'"}],"responses":{"200":{"description":"DNS check results","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"taken":{"type":"array","items":{"type":"string"},"description":"TLDs that are definitely registered"},"candidates":{"type":"array","items":{"type":"string"},"description":"TLDs that are potentially available"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Query parameter 'name' is required","code":"MISSING_PARAMETER","hint":"Provide both 'name' and 'tlds' query parameters","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/tokens":{"get":{"operationId":"listTokens","summary":"List your API tokens","description":"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.","tags":["API Tokens"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/tokens \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"responses":{"200":{"description":"List of API tokens","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/TokenInfo"}}}},"example":{"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"}]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"post":{"operationId":"createToken","summary":"Create a new API token","description":"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.","tags":["API Tokens"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/tokens \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"CI/CD Pipeline\"}'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"CI/CD Pipeline","description":"Human-readable name to identify this token"},"expires_in":{"type":"integer","example":2592000,"description":"Token lifetime in seconds (min 3600 = 1h, max 31536000 = 1y). Omit for no expiration."},"expires_at":{"type":"string","format":"date-time","description":"Absolute expiration date (ISO 8601). Alternative to expires_in."},"scopes":{"type":"array","items":{"type":"string"},"description":"Permission scopes for this token. Use ['*'] for full access (default). A token can only grant scopes it already has (scope attenuation). Scopes: domains:read (GET /api/domains, GET /api/domains/{domain}, GET /api/domains/{domain}/dns, /status, /email/check, /auth-code, /transfer-away, /transfer-status, /analytics), domains:write (PUT /api/domains/{domain}/dns, POST /connect, POST /verify, PUT /settings, PUT /parking, PUT/DELETE /api/domains/{domain}/for-sale, POST /api/domains/import, POST /import/verify), domains:transfer (POST /api/domains/buy, POST /transfer, POST /renew (involves payment, includes marketplace purchases)), tokens:read (GET /api/tokens), tokens:write (POST /api/tokens, DELETE /api/tokens/{id}), webhooks:read (GET /api/webhooks, GET /api/webhooks/{id}/deliveries), webhooks:write (POST /api/webhooks, PATCH /api/webhooks/{id}, DELETE /api/webhooks/{id}), email:read (GET /api/emails, /api/emails/{address}, /api/emails/{address}/messages, /api/domains/{domain}/email/status), email:write (POST /api/emails, POST /api/emails/{address}/send, POST /api/domains/{domain}/email/setup), account:read (GET /api/me), account:write (DELETE /api/me, POST /api/billing/setup, POST /api/me/resend-verification), billing:read (GET /api/billing/invoices), search (GET /api/domains/search, /suggest, /whois, /dns-check, GET /api/tlds), deals:read (GET /api/deals, GET /api/deals/{id}), deals:write (POST /api/domains/sell, PATCH /api/deals/{id}), notifications:read (GET /api/notifications, GET /api/notifications/count)."}}},"example":{"name":"CI/CD Pipeline","expires_in":2592000,"scopes":["domains:read","domains:write"]}}}},"responses":{"201":{"description":"Token created - save the key, it won't be shown again","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key":{"type":"string","description":"Full API key - save this, it won't be shown again"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"When this token expires (null = never)"},"scopes":{"type":"array","items":{"type":"string"},"description":"Permission scopes granted to this token"},"createdAt":{"type":"string","format":"date-time"}}},"example":{"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"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"403":{"description":"Token lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Token does not have the required scope for this action","code":"INSUFFICIENT_SCOPE","hint":"Required scope: tokens:write. Create a new token with the needed scopes.","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/tokens/{id}":{"delete":{"operationId":"revokeToken","summary":"Revoke an API token","description":"Permanently revokes an API token. Any applications using this token will immediately lose access. This action cannot be undone.","tags":["API Tokens"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X DELETE https://domani.run/api/tokens/cm5abc123 \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"cm5abc123"},"description":"Token ID (from GET /api/tokens response)"}],"responses":{"200":{"description":"Token revoked successfully","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Token not found","code":"NOT_FOUND","hint":"Verify the token exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/billing/setup":{"post":{"operationId":"setupBilling","summary":"Get checkout URL for adding a payment method","description":"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.","tags":["Billing"],"x-rateLimit":{"limit":60,"window":"1 minute"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["setup_intent","checkout"],"default":"setup_intent","description":"setup_intent returns a client_secret for frontend Stripe.js. checkout returns a URL to redirect the user to Stripe Checkout."}}}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/billing/setup \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"mode\": \"checkout\"}'"}],"responses":{"200":{"description":"Checkout URL or client secret depending on mode","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Checkout URL (checkout mode)"},"client_secret":{"type":"string","description":"Stripe SetupIntent client secret (setup_intent mode)"},"hint":{"type":"string","description":"Next steps guidance"}}},"example":{"url":"https://checkout.domani.run/session/cs_abc123...","hint":"Open this URL in a browser to add your payment card."}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/billing/card":{"delete":{"operationId":"removeCard","summary":"Remove saved payment method","description":"Detaches the user's saved credit card from their account. After removal, a new card must be added before purchasing domains.","tags":["Billing"],"x-rateLimit":{"limit":10,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X DELETE https://domani.run/api/billing/card \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"responses":{"200":{"description":"Card removed","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"}}},"example":{"removed":true}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/billing/invoices":{"get":{"operationId":"listInvoices","summary":"List payment invoices","description":"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.","tags":["Billing"],"x-rateLimit":{"limit":30,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/billing/invoices \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Max invoices to return"}],"responses":{"200":{"description":"List of invoices","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string","nullable":true},"status":{"type":"string"},"amount_due":{"type":"integer","description":"Amount in cents"},"amount_paid":{"type":"integer","description":"Amount in cents"},"currency":{"type":"string"},"description":{"type":"string","nullable":true},"created":{"type":"string","format":"date-time"},"hosted_invoice_url":{"type":"string","format":"uri","nullable":true,"description":"URL to view the invoice in browser"},"invoice_pdf":{"type":"string","format":"uri","nullable":true,"description":"Direct PDF download URL"}}}},"has_more":{"type":"boolean"},"hint":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/referrals":{"get":{"operationId":"getReferrals","summary":"Get referral earnings and history","description":"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.","tags":["Referrals"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/referrals \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"responses":{"200":{"description":"Referral code, earnings, and history","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"referral_code":{"type":"string","description":"Your unique referral code to share"},"referral_rate":{"type":"integer","description":"Commission percentage (currently 20%)"},"total_earned_cents":{"type":"integer","description":"Total earnings in cents"},"total_paid_cents":{"type":"integer","description":"Total paid out in cents"},"total_pending_cents":{"type":"integer","description":"Pending payout in cents"},"referrals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"domains":{"type":"array","items":{"type":"string"}},"earned_cents":{"type":"integer"},"paid_out":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}},"example":{"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"}]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhooks","description":"List all webhook endpoints configured for your account. Returns URL, subscribed events, and active status for each webhook. Secrets are never returned after creation.","tags":["Webhooks"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/webhooks \\\n  -H \"Authorization: Bearer domani_sk_xxx\""}],"responses":{"200":{"description":"List of webhooks","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}},"hint":{"type":"string"}}},"example":{"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)."}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"post":{"operationId":"createWebhook","summary":"Create webhook","description":"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.","tags":["Webhooks"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://domani.run/api/webhooks \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\":\"https://example.com/hook\",\"events\":[\"domain.purchased\",\"dns.updated\"]}'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL that will receive webhook POST requests"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to subscribe to. Use GET /api/webhooks/events to list available types."}}},"example":{"url":"https://example.com/webhooks/domani","events":["domain.purchased","dns.updated","transfer.completed"]}}}},"responses":{"200":{"description":"Webhook created. Secret is included only in this response.","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string","description":"HMAC-SHA256 signing secret (shown once)"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"hint":{"type":"string"}}},"example":{"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."}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Unknown event type(s): invalid.event","code":"INVALID_PARAMETER","hint":"Use GET /api/webhooks/events to list valid event types","documentation_url":"https://domani.run/llms.txt"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/webhooks/{id}":{"patch":{"operationId":"updateWebhook","summary":"Update webhook","description":"Update a webhook's URL, subscribed events, or active status. Send only the fields you want to change.","tags":["Webhooks"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"New HTTPS URL"},"events":{"type":"array","items":{"type":"string"},"description":"New list of event types"},"active":{"type":"boolean","description":"Set false to pause, true to resume"}}},"examples":{"pause":{"summary":"Pause webhook","value":{"active":false}},"updateEvents":{"summary":"Change events","value":{"events":["domain.purchased","transfer.completed"]}}}}}},"responses":{"200":{"description":"Webhook updated","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"hint":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Webhook not found","code":"NOT_FOUND","hint":"Verify the webhook exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}},"delete":{"operationId":"deleteWebhook","summary":"Delete webhook","description":"Delete a webhook endpoint. All pending deliveries will be cancelled. This cannot be undone.","tags":["Webhooks"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"}],"responses":{"200":{"description":"Webhook deleted","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"hint":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Webhook not found","code":"NOT_FOUND","hint":"Verify the webhook exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/webhooks/{id}/deliveries":{"get":{"operationId":"getWebhookDeliveries","summary":"List webhook deliveries","description":"Get recent delivery attempts for a webhook. Shows event type, HTTP status, number of attempts, and any errors. Useful for debugging failed deliveries.","tags":["Webhooks"],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of deliveries to return"}],"responses":{"200":{"description":"Delivery history","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000}},"content":{"application/json":{"schema":{"type":"object","properties":{"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event_type":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"]},"http_status":{"type":"integer","nullable":true},"attempts":{"type":"integer"},"last_error":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"hint":{"type":"string"}}},"example":{"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."}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No Authorization header","value":{"error":"Missing API key","code":"MISSING_API_KEY","hint":"Include 'Authorization: Bearer domani_sk_xxx' header","documentation_url":"https://domani.run/llms.txt"}},"invalid":{"summary":"Invalid or revoked key","value":{"error":"Invalid API key","code":"INVALID_API_KEY","hint":"Check your API key or create a new one at POST /api/tokens","documentation_url":"https://domani.run/llms.txt"}},"expired":{"summary":"Token has expired","value":{"error":"API key has expired","code":"EXPIRED_API_KEY","hint":"Create a new token via POST /api/tokens or run 'domani login'","documentation_url":"https://domani.run/llms.txt"}}}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Webhook not found","code":"NOT_FOUND","hint":"Verify the webhook exists and belongs to you","documentation_url":"https://domani.run/llms.txt"}}}},"429":{"description":"Rate limit exceeded - wait and retry","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"},"example":60},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window","schema":{"type":"integer"},"example":57},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the window resets","schema":{"type":"integer"},"example":1700000000},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","hint":"Wait 30 seconds before retrying","retry_after":30,"documentation_url":"https://domani.run/llms.txt"}}}}}}},"/api/webhooks/events":{"get":{"operationId":"listWebhookEvents","summary":"List webhook event types","description":"List all available webhook event types with descriptions. No authentication required.","tags":["Webhooks"],"x-rateLimit":{"limit":60,"window":"1 minute"},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl https://domani.run/api/webhooks/events"}],"responses":{"200":{"description":"Available event types","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"}}}}}},"example":{"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"}]}}}}}}},"/api/domains/{domain}/email/setup":{"post":{"operationId":"setupDomainEmail","summary":"Set up email on a domain","description":"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).","tags":["Email"],"security":[{"BearerAuth":[]}],"x-rateLimit":{"limit":60,"window":"1 minute"},"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"Domain name"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Override existing email provider (Google Workspace, Fastmail, Proton). Default: false"}}}}}},"responses":{"200":{"description":"Email set up successfully","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["configured","already_configured"]},"verified_at":{"type":"string","nullable":true},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"hint":{"type":"string"}}}}}},"400":{"description":"Conflict - external email provider active. Pass force=true to override"}}},"delete":{"operationId":"removeDomainEmail","summary":"Remove email from a domain","description":"Remove email from a domain, delete all mailboxes and messages, and set emailEnabled to false.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"Domain name"}],"responses":{"200":{"description":"Email removed successfully"}}}},"/api/domains/{domain}/email/status":{"get":{"operationId":"getDomainEmailStatus","summary":"Check email DNS status","description":"Check email DNS verification status for a domain. Returns whether the domain is verified and ready, DNS record details, and mailbox count.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"Domain name"}],"responses":{"200":{"description":"Email status","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"verified":{"type":"boolean"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"mailbox_count":{"type":"integer"}}}}}}}}},"/api/email":{"post":{"operationId":"createMailbox","summary":"Create a mailbox on domani.run","description":"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.","tags":["Email"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","description":"Local part of the email address (e.g. 'hello' for hello@domani.run)"},"name":{"type":"string","description":"Display name (defaults to capitalized slug)"}}}}}},"responses":{"200":{"description":"Mailbox created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"}}}}}}}},"get":{"operationId":"listMailboxes","summary":"List all mailboxes","description":"List all email addresses (mailboxes) owned by the user across all domains.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"domain","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by domain"}],"responses":{"200":{"description":"Mailbox list","content":{"application/json":{"schema":{"type":"object","properties":{"mailboxes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"message_count":{"type":"integer"}}}}}}}}}}}},"/api/emails":{"post":{"operationId":"createMailboxByAddress","summary":"Create a mailbox","description":"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.","tags":["Email"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Full email address, e.g. hello@mysite.com"},"name":{"type":"string","description":"Display name for outbound emails (e.g. \"John Doe\")"},"force":{"type":"boolean","description":"Override existing MX records. Default: false"}},"required":["address"]}}}},"responses":{"200":{"description":"Mailbox created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"name":{"type":"string","nullable":true},"domain":{"type":"string"},"slug":{"type":"string"},"webhook_url":{"type":"string","nullable":true},"forward_to":{"type":"string","nullable":true},"signing_secret":{"type":"string","description":"HMAC secret for verifying inbound webhook payloads (shown once at creation)"}}}}}}}},"get":{"operationId":"listMailboxesByAddress","summary":"List all mailboxes","description":"List all email addresses (mailboxes) owned by the user across all domains. Same as GET /api/email.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"domain","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by domain"}],"responses":{"200":{"description":"Mailbox list","content":{"application/json":{"schema":{"type":"object","properties":{"mailboxes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"message_count":{"type":"integer"},"webhook_url":{"type":"string","nullable":true},"forward_to":{"type":"string","nullable":true}}}}}}}}}}}},"/api/emails/{address}":{"get":{"operationId":"getMailboxByAddress","summary":"Get mailbox details","description":"Get details for a specific mailbox by its full email address (URL-encoded, e.g. hello%40mysite.com).","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Full email address (URL-encoded, e.g. hello%40mysite.com)"}],"responses":{"200":{"description":"Mailbox details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"webhook_url":{"type":"string","nullable":true},"forward_to":{"type":"string","nullable":true},"signing_secret":{"type":"string","description":"HMAC secret for verifying inbound webhook payloads"},"message_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"patch":{"operationId":"updateMailboxByAddress","summary":"Update mailbox","description":"Update a mailbox's display name, webhook URL, or forward-to email address by its full email address. Set to null to disable/clear.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Full email address (URL-encoded)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Display name for the mailbox. Set to null to clear."},"webhook_url":{"type":"string","nullable":true,"description":"HTTPS URL for inbound email webhook, or null to clear"},"forward_to":{"type":"string","nullable":true,"description":"Email address to forward inbound emails to, or null to clear"}}}}}},"responses":{"200":{"description":"Mailbox updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string","nullable":true},"webhook_url":{"type":"string","nullable":true},"forward_to":{"type":"string","nullable":true},"signing_secret":{"type":"string","description":"HMAC secret for verifying inbound webhook payloads"}}}}}}}},"delete":{"operationId":"deleteMailboxByAddress","summary":"Delete a mailbox","description":"Delete a mailbox by its full email address. Requires confirm=true in body. Without confirm, returns a preview with message_count.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Full email address (URL-encoded)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","description":"Must be true to actually delete. Omit to preview."}}}}}},"responses":{"200":{"description":"Mailbox deleted (if confirm=true) or preview (if omitted)"}}}},"/api/emails/{address}/send":{"post":{"operationId":"sendEmailByAddress","summary":"Send an email","description":"Send an email from a mailbox identified by its full email address. Rate limit: 100 emails per hour per mailbox.","tags":["Email"],"security":[{"BearerAuth":[]}],"x-rateLimit":{"limit":100,"window":"1 hour","scope":"per mailbox"},"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Sender email address (URL-encoded)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Unique key to prevent duplicate sends"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Recipient email address(es)"},"cc":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"CC recipient(s)"},"bcc":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"BCC recipient(s)"},"subject":{"type":"string"},"text":{"type":"string","description":"Plain text body"},"html":{"type":"string","description":"HTML body"},"reply_to":{"type":"string","description":"Reply-To address"},"in_reply_to":{"type":"string","description":"Message-ID of the email being replied to (for threading)"},"references":{"type":"string","description":"Space-separated Message-ID chain (for threading)"},"attachments":{"type":"array","description":"File attachments (max 10, max 40MB total). Content must be base64-encoded.","items":{"type":"object","properties":{"content":{"type":"string","description":"Base64-encoded file content"},"filename":{"type":"string","description":"Filename with extension"},"content_type":{"type":"string","description":"MIME type (optional)"}},"required":["content","filename"]}}},"required":["to"]}}}},"responses":{"200":{"description":"Email sent","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"message_id":{"type":"string","description":"RFC 5322 Message-ID"},"from":{"type":"string"},"to":{"type":"string"},"status":{"type":"string"},"attachments_count":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded (100/hr per mailbox)"}}}},"/api/emails/{address}/messages":{"get":{"operationId":"listEmailMessagesByAddress","summary":"List emails","description":"List emails sent and received by a mailbox identified by its full email address. Supports cursor-based pagination and direction filtering.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination cursor from previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"maximum":100},"description":"Max messages to return"},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["in","out","all"]},"description":"Filter by direction (default: all)"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp - return only messages created after this date"},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by sender address"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by recipient address"},{"name":"subject","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by subject"}],"responses":{"200":{"description":"Message list","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"message_id":{"type":"string","nullable":true},"direction":{"type":"string","enum":["in","out"]},"from":{"type":"string"},"to":{"type":"string"},"cc":{"type":"string","nullable":true},"reply_to":{"type":"string","nullable":true},"subject":{"type":"string"},"text":{"type":"string"},"in_reply_to":{"type":"string","nullable":true},"references":{"type":"string","nullable":true},"status":{"type":"string","enum":["queued","sent","delivered","delayed","bounced","failed","complained","suppressed"]},"events":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"detail":{"type":"object","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"created_at":{"type":"string","format":"date-time"}}}},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}},"/api/emails/{address}/messages/read":{"patch":{"operationId":"markMessagesReadByAddress","summary":"Mark messages as read or unread","description":"Mark one or more messages as read or unread in a mailbox identified by its full email address.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message_ids":{"type":"array","items":{"type":"string"},"description":"IDs of messages to mark"},"read":{"type":"boolean","description":"true to mark as read, false to mark as unread"}},"required":["message_ids","read"]}}}},"responses":{"200":{"description":"Messages updated","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"}}}}}}}}},"/api/emails/{address}/messages/delete":{"post":{"operationId":"deleteMessagesByAddress","summary":"Bulk delete messages","description":"Soft-delete multiple messages at once in a mailbox identified by its full email address.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message_ids":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"IDs of messages to delete"}},"required":["message_ids"]}}}},"responses":{"200":{"description":"Messages deleted","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"}}}}}},"404":{"description":"Mailbox not found"}}}},"/api/emails/{address}/messages/{id}":{"get":{"operationId":"getMessageByAddress","summary":"Get a message","description":"Fetch a single message by ID from a mailbox identified by its full email address.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Message ID"}],"responses":{"200":{"description":"Message details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"message_id":{"type":"string","nullable":true},"direction":{"type":"string","enum":["in","out"]},"from":{"type":"string"},"to":{"type":"string"},"cc":{"type":"string","nullable":true},"reply_to":{"type":"string","nullable":true},"subject":{"type":"string"},"text":{"type":"string","nullable":true},"html":{"type":"string","nullable":true},"in_reply_to":{"type":"string","nullable":true},"references":{"type":"string","nullable":true},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"size":{"type":"integer"},"url":{"type":"string","nullable":true}}}},"status":{"type":"string"},"is_read":{"type":"boolean"},"read_at":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"detail":{"type":"object","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"created_at":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Mailbox or message not found"}}},"delete":{"operationId":"deleteMessageByAddress","summary":"Delete a message","description":"Soft-delete a message from a mailbox identified by its full email address.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Message ID"}],"responses":{"200":{"description":"Message deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"404":{"description":"Mailbox or message not found"}}}},"/api/emails/{address}/messages/{id}/reply":{"post":{"operationId":"replyToMessageByAddress","summary":"Reply to a message","description":"Reply to a message in a mailbox identified by its full email address. Threading headers are auto-populated.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Message ID to reply to"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Plain text reply body"},"html":{"type":"string","description":"HTML reply body"},"cc":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Additional CC recipient(s)"},"all":{"type":"boolean","default":false,"description":"Reply-all: auto-populate CC from original To/CC"}}}}}},"responses":{"200":{"description":"Reply sent","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"message_id":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"Missing body (provide text or html)"},"404":{"description":"Mailbox or message not found"}}}},"/api/emails/{address}/messages/{id}/forward":{"post":{"operationId":"forwardMessageByAddress","summary":"Forward a message","description":"Forward a message from a mailbox identified by its full email address to another recipient.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Message ID to forward"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Recipient email address"},"text":{"type":"string","description":"Optional note to prepend"}},"required":["to"]}}}},"responses":{"200":{"description":"Message forwarded","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"message_id":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"status":{"type":"string"}}}}}},"404":{"description":"Mailbox or message not found"}}}},"/api/emails/{address}/avatar":{"get":{"operationId":"getMailboxAvatarByAddress","summary":"Get mailbox avatar info","description":"Returns the Gravatar URL (if set) and signup link for a mailbox identified by its full email address.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"}],"responses":{"200":{"description":"Avatar info","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"gravatar_url":{"type":"string","nullable":true},"gravatar_signup":{"type":"string"},"has_avatar":{"type":"boolean"},"hint":{"type":"string"}}}}}}}}},"/api/emails/{address}/webhook":{"get":{"operationId":"getMailboxWebhook","summary":"Get mailbox webhook config","description":"Returns the webhook URL, signing secret, and status for a mailbox.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"}],"responses":{"200":{"description":"Webhook config","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"webhook_url":{"type":"string","nullable":true},"signing_secret":{"type":"string","nullable":true},"has_webhook":{"type":"boolean"},"hint":{"type":"string"}}}}}}}},"put":{"operationId":"setMailboxWebhook","summary":"Set mailbox webhook","description":"Set or update the inbound webhook URL for a mailbox. Incoming emails will be POSTed to this URL with HMAC-SHA256 signing.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"HTTPS webhook URL"}}}}}},"responses":{"200":{"description":"Webhook set","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"webhook_url":{"type":"string"},"signing_secret":{"type":"string"},"has_webhook":{"type":"boolean"},"hint":{"type":"string"}}}}}}}},"delete":{"operationId":"removeMailboxWebhook","summary":"Remove mailbox webhook","description":"Remove the webhook URL and signing secret from a mailbox. Inbound emails will only be stored.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"}],"responses":{"200":{"description":"Webhook removed","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"webhook_url":{"type":"string","nullable":true},"signing_secret":{"type":"string","nullable":true},"has_webhook":{"type":"boolean"},"hint":{"type":"string"}}}}}}}}},"/api/emails/{address}/webhook/rotate":{"post":{"operationId":"rotateMailboxWebhookSecret","summary":"Rotate webhook signing secret","description":"Regenerate the HMAC-SHA256 signing secret for a mailbox webhook. The old secret is immediately invalidated.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"}],"responses":{"200":{"description":"Secret rotated","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"webhook_url":{"type":"string"},"signing_secret":{"type":"string"},"has_webhook":{"type":"boolean"},"hint":{"type":"string"}}}}}}}}},"/api/emails/{address}/webhook/test":{"post":{"operationId":"testMailboxWebhook","summary":"Test mailbox webhook","description":"Send a signed test payload to the mailbox webhook URL. Returns HTTP status and whether delivery succeeded.","tags":["Email"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox email address (URL-encoded)"}],"responses":{"200":{"description":"Test result","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"webhook_url":{"type":"string"},"status":{"type":"integer"},"success":{"type":"boolean"},"hint":{"type":"string"}}}}}}}}}}}