{"openapi":"3.1.0","info":{"title":"DomainFast Agent API","version":"1.0.0","description":"Public, read-only domain research tools. No API key required. Queries are logged for reliability and abuse prevention. At most 50 domains per lookup. Names and domains must be ASCII or punycode. No purchases, registrations, or live prices. Call from your server; arbitrary browser origins are not supported. Use exponential backoff for retryable failures."},"servers":[{"url":"https://www.domainfast.ai"}],"security":[],"paths":{"/api/v1/domain-checks":{"post":{"operationId":"check_domains","summary":"Check domain availability","description":"Check 1–50 complete domains using RDAP/WHOIS. Returns available, registered, or unknown, with source and observation time. Unknown is not available. Results do not guarantee purchasability or include live prices. Public queries are logged for service reliability and abuse prevention.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"domains":{"description":"Domains to check. Duplicates are removed, preserving first occurrence order.","minItems":1,"maxItems":50,"type":"array","items":{"description":"A complete ASCII or punycode domain, without a URL scheme or path.","type":"string","minLength":3,"maxLength":253,"pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$"}}},"required":["domains"],"additionalProperties":false}}}},"responses":{"200":{"description":"Completed. Inspect each result status; unknown is not available.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"request_id":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["available","registered","unknown"]},"available":{"description":"Null for unknown. Never interpret null as available.","anyOf":[{"type":"boolean"},{"type":"null"}]},"reason":{"type":"string"},"checked_at":{"description":"Time of the underlying observation; cached observations can be older than this request.","anyOf":[{"type":"string"},{"type":"null"}]},"cached":{"type":"boolean"},"source":{"type":"object","properties":{"kind":{"type":"string"},"authority":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","authority"],"additionalProperties":false}},"required":["domain","status","available","reason","checked_at","cached","source"],"additionalProperties":false}},"summary":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"registered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unknown":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["total","available","registered","unknown"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["request_id","results","summary","warnings"],"additionalProperties":false}}}},"400":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"403":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"413":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"415":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"429":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"500":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"502":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"503":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"504":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}}}}},"/api/v1/domain-searches":{"post":{"operationId":"search_domains","summary":"Search a name across suffixes","description":"Check a name across 1–50 explicit suffixes in one call, including multi-part suffixes like com.cn. Returns the same evidence and statuses as check_domains. Does not register or buy domains. Public queries are logged.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"description":"A single brand/name label, without dots, spaces, or a URL.","type":"string","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"},"suffixes":{"description":"Explicit suffixes to check for this name. No suffixes are silently added.","minItems":1,"maxItems":50,"type":"array","items":{"description":"A suffix without a leading dot, for example com, ai, or com.cn.","type":"string","minLength":2,"maxLength":189,"pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"}}},"required":["name","suffixes"],"additionalProperties":false}}}},"responses":{"200":{"description":"Completed. Inspect each result status; unknown is not available.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"request_id":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["available","registered","unknown"]},"available":{"description":"Null for unknown. Never interpret null as available.","anyOf":[{"type":"boolean"},{"type":"null"}]},"reason":{"type":"string"},"checked_at":{"description":"Time of the underlying observation; cached observations can be older than this request.","anyOf":[{"type":"string"},{"type":"null"}]},"cached":{"type":"boolean"},"source":{"type":"object","properties":{"kind":{"type":"string"},"authority":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","authority"],"additionalProperties":false}},"required":["domain","status","available","reason","checked_at","cached","source"],"additionalProperties":false}},"summary":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"registered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unknown":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["total","available","registered","unknown"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["request_id","results","summary","warnings"],"additionalProperties":false}}}},"400":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"403":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"413":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"415":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"429":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"500":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"502":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"503":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"504":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}}}}},"/api/v1/domain-suggestions":{"post":{"operationId":"suggest_domain_names","summary":"Suggest domain name candidates","description":"Generate alternative name labels. These are ideas, NOT verified available domains. Pass them to search_domains or check_domains to verify. The strategy field indicates AI or rule-based fallback.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"description":"A single brand/name label, without dots, spaces, or a URL.","type":"string","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"},"limit":{"description":"Maximum number of name suggestions. Suggestions are not availability checks.","default":6,"type":"integer","minimum":1,"maximum":20}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Completed. Inspect each result status; unknown is not available.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"request_id":{"type":"string"},"name":{"type":"string"},"suggestions":{"type":"array","items":{"type":"string"}},"strategy":{"type":"string","enum":["ai","fallback"]},"availability_checked":{"type":"boolean","const":false}},"required":["request_id","name","suggestions","strategy","availability_checked"],"additionalProperties":false}}}},"400":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"403":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"413":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"415":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"429":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"500":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"502":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"503":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}},"504":{"description":"Structured error. Retry only when error.retryable is true, using backoff and Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}},"headers":{"Retry-After":{"description":"Minimum retry delay in seconds, when retryable.","schema":{"type":"integer"}}}}}}}},"components":{"schemas":{"AgentError":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}},"required":["field","message"],"additionalProperties":false}}},"required":["code","message","retryable"],"additionalProperties":false}},"required":["request_id","error"],"additionalProperties":false}}}}