{"openapi":"3.1.0","info":{"title":"AgentDomain API","description":"Headless domain registrar SaaS for AI agents. Search, register, renew, and manage domains via REST API.","version":"1.0.0","contact":{"url":"https://domainforagents.io"}},"servers":[{"url":"https://api.domainforagents.io/api/v1","description":"Production"},{"url":"http://localhost:3000/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key obtained from POST /auth/register"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"state":{"type":"string","enum":["available","soft_reserved","payment_pending","registering","registered","transferring","expired","failed"]},"registrationDate":{"type":"string","format":"date-time","nullable":true},"expiryDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"registrantUpdateDeadline":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"DnsRecord":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SRV","CAA"]},"content":{"type":"string"},"ttl":{"type":"integer","default":3600},"priority":{"type":"integer","nullable":true}},"required":["name","type","content"]}}},"paths":{"/auth/register":{"post":{"summary":"Create account and get API key","description":"Agent-first: no email required. Returns API key + claim code for human account claiming.","tags":["Authentication"],"security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Optional email"},"name":{"type":"string","description":"Name for the first API key"}}}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid"},"api_key":{"type":"string"},"claim_code":{"type":"string","example":"AGENT-SWIFT-KIWI-7842"},"sign_in_url":{"type":"string","format":"uri"}}}}}}}}},"/auth/keys":{"post":{"summary":"Create API key","tags":["Authentication"],"responses":{"201":{"description":"Key created"}}},"get":{"summary":"List API keys","tags":["Authentication"],"responses":{"200":{"description":"Key list"}}}},"/auth/keys/rotate":{"post":{"summary":"Rotate API key","description":"Invalidates the current key and returns a new one.","tags":["Authentication"],"responses":{"200":{"description":"New key issued"}}}},"/auth/claim-code":{"post":{"summary":"Generate new claim code","tags":["Authentication"],"responses":{"200":{"description":"New claim code"}}}},"/account":{"patch":{"summary":"Update account","description":"Update email and notification preferences.","tags":["Account"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"notificationPreferences":{"type":"object","additionalProperties":{"type":"boolean"}}}}}}},"responses":{"200":{"description":"Account updated"}}}},"/domains/search":{"get":{"summary":"Search domain availability","tags":["Domains"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Search results with pricing and availability"}}}},"/domains":{"get":{"summary":"List your domains","tags":["Domains"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"state","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated domain list"}}}},"/domains/reserve":{"post":{"summary":"Soft-reserve a domain","description":"Creates a TTL-based soft reservation. Returns a payment URL. No upstream registration until paid.","tags":["Domains"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"ttlSeconds":{"type":"integer","minimum":300,"maximum":21600}},"required":["name"]}}}},"responses":{"201":{"description":"Reservation created","content":{"application/json":{"schema":{"type":"object","properties":{"reservation_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string"},"price_usd":{"type":"number"},"expires_at":{"type":"string","format":"date-time"},"payment_url":{"type":"string","format":"uri"},"guaranteed":{"type":"boolean"}}}}}}}}},"/domains/reserve/{id}/pay":{"post":{"summary":"Finalize reservation payment","tags":["Domains"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Registration initiated"}}}},"/domains/register":{"post":{"summary":"Register a domain","description":"Supports balance, card, or crypto payment. Triggers async upstream registration.","tags":["Domains"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"years":{"type":"integer","default":1},"paymentMethod":{"oneOf":[{"type":"object","properties":{"type":{"const":"balance"}},"required":["type"]},{"type":"object","properties":{"type":{"const":"card"},"card":{"type":"object","properties":{"number":{"type":"string"},"expMonth":{"type":"integer"},"expYear":{"type":"integer"},"cvc":{"type":"string"}},"required":["number","expMonth","expYear","cvc"]},"saveCard":{"type":"boolean"}},"required":["type","card"]},{"type":"object","properties":{"type":{"const":"crypto"}},"required":["type"]}]},"dnsRecords":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}},"required":["name"]}}}},"responses":{"202":{"description":"Registration initiated"},"402":{"description":"Payment required"}}}},"/domains/{id}":{"get":{"summary":"Get domain details","tags":["Domains"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Domain details with DNS records"}}}},"/domains/{id}/renew":{"post":{"summary":"Renew domain","tags":["Domains"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Renewal initiated"}}}},"/domains/{id}/registrant":{"patch":{"summary":"Update WHOIS registrant","description":"Must be within the 30-day update window.","tags":["Domains"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Update initiated"}}}},"/domains/{id}/dns":{"get":{"summary":"List DNS records","tags":["DNS"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"DNS records"}}},"post":{"summary":"Create DNS record","tags":["DNS"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Record created"}}},"put":{"summary":"Replace all DNS records","description":"Full replacement. Records not included will be deleted.","tags":["DNS"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Replacement queued"}}},"patch":{"summary":"Update DNS records","description":"Merge-safe partial update.","tags":["DNS"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Update queued"}}}},"/domains/{id}/dns/{recordId}":{"delete":{"summary":"Delete DNS record","tags":["DNS"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"recordId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Record deleted"}}}},"/domains/{id}/nameservers":{"put":{"summary":"Set custom nameservers","description":"Disables managed DNS.","tags":["DNS"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Nameserver update queued"}}}},"/domains/{id}/nameservers/default":{"post":{"summary":"Reset to default nameservers","description":"Re-enables managed DNS.","tags":["DNS"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Reset queued"}}}},"/balance":{"get":{"summary":"Get balance","tags":["Payments"],"responses":{"200":{"description":"Balance and transaction history"}}}},"/balance/topup":{"post":{"summary":"Top up balance","description":"Creates a Stripe PaymentIntent for adding funds.","tags":["Payments"],"responses":{"200":{"description":"Payment intent created"}}}},"/payments/stripe/intent":{"post":{"summary":"Create Stripe payment intent","tags":["Payments"],"responses":{"200":{"description":"Client secret returned"}}}},"/payments/solana/deposit":{"get":{"summary":"Get USDC deposit info","description":"Returns platform Solana wallet address. Send USDC (SPL) with your account ID in the memo field. Balance credited 1:1.","tags":["Payments"],"responses":{"200":{"description":"Wallet address and USDC mint"}}}},"/webhooks":{"get":{"summary":"List webhooks","tags":["Webhooks"],"responses":{"200":{"description":"Webhook list"}}},"post":{"summary":"Register webhook","description":"Subscribe to events. Returns a signing secret.","tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["domain.registered","domain.renewed","domain.expired","domain.failed","domain.transferred","payment.confirmed","payment.failed","reservation.expired"]}}},"required":["url","events"]}}}},"responses":{"201":{"description":"Webhook created with secret"}}}},"/webhooks/{id}":{"delete":{"summary":"Delete webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook deleted"}}}}}}