{"openapi":"3.1.0","info":{"title":"names.dev public search","version":"2.0.0","description":"Public, read-only naming and domain evidence. No purchase or private-account operations. Amounts are USD cents unless an evidence price specifies a different currency."},"servers":[{"url":"https://api.names.dev"}],"security":[],"paths":{"/v2/search":{"post":{"operationId":"names_search","summary":"Search a domain, a name or a product brief","description":"Exact domains are checked first; bare labels check the same name across endings. Relevance is gated before brief alternatives are shown. Read registration and marketplace evidence separately. Provider issues and unknown observations are explicit. Acquisition happens at the source provider.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"},"example":{"query":"a social running app","tlds":["com","app"],"budgetMaxUsdCents":50000,"limit":6}}}},"responses":{"200":{"description":"Search evidence. Empty results are valid; inspect diagnostics.issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid query, domain, ending, limit or budget."},"413":{"description":"Request body exceeds 16 KiB."},"429":{"description":"Public rate limit reached. Wait before retrying.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"Search or request limiting is unavailable."},"504":{"description":"Search deadline reached."}}}}},"components":{"schemas":{"SearchRequest":{"type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":2000,"description":"One exact domain, a bare name, or a product brief. Preserve the user's intended naming category."},"limit":{"type":"integer","minimum":1,"maximum":12,"description":"Maximum names to return, from 1 to 12. Fewer strong names may be returned."},"tlds":{"type":"array","items":{"type":"string","minLength":2,"maxLength":40,"pattern":"^\\.?[a-z0-9-]+(?:\\.[a-z0-9-]+)*$"},"maxItems":12,"description":"Preferred domain endings, for example com, app or co.uk, in preference order."},"budgetMaxUsdCents":{"type":"integer","minimum":0,"maximum":1000000000000,"description":"Maximum acquisition budget in USD cents; $500 is 50000. Prices remain provider observations."}},"required":["query"],"additionalProperties":false},"SearchResponse":{"type":"object","properties":{"version":{"type":"number","const":2},"requestId":{"type":"string"},"query":{"type":"string"},"mode":{"type":"string","enum":["EXACT_DOMAIN","LABEL_ONLY","MIXED_LABEL_AND_BRIEF","BRIEF"]},"seedLabel":{"type":"string"},"exactDomain":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"meaning":{"type":"string"},"why":{"type":"string"},"origin":{"type":"string","enum":["requested","generated","inventory"]},"primaryDomain":{"type":"string"},"fit":{"type":"string","enum":["strong","good"]},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"registration":{"type":"object","properties":{"kind":{"type":"string","const":"registration"},"domain":{"type":"string"},"provider":{"type":"string"},"sourceTrust":{"type":"string","enum":["LIVE_REGISTRAR","RDAP_DNS_HINT","SEARCH_HINT"]},"state":{"type":"string","enum":["registerable","taken","blocked","looks_clear","unknown"]},"checkedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"price":{"type":"object","properties":{"amountCents":{"type":"integer","minimum":0},"currency":{"type":"string"},"termYears":{"type":"integer","exclusiveMinimum":0}},"required":["amountCents","currency"],"additionalProperties":false},"renewalPrice":{"type":"object","properties":{"amountCents":{"type":"integer","minimum":0},"currency":{"type":"string"},"termYears":{"type":"integer","exclusiveMinimum":0}},"required":["amountCents","currency"],"additionalProperties":false},"url":{"type":"string","format":"uri"},"note":{"type":"string"}},"required":["kind","domain","provider","sourceTrust","state","checkedAt"],"additionalProperties":false},"offers":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","const":"listing"},"domain":{"type":"string"},"provider":{"type":"string"},"sourceTrust":{"type":"string","const":"LIVE_MARKETPLACE"},"state":{"type":"string","enum":["active","unknown","removed"]},"listingType":{"type":"string","enum":["buy_now","make_offer","auction","lease_to_own","unknown"]},"checkedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"price":{"type":"object","properties":{"amountCents":{"type":"integer","minimum":0},"currency":{"type":"string"},"termYears":{"type":"integer","exclusiveMinimum":0}},"required":["amountCents","currency"],"additionalProperties":false},"minimumOffer":{"type":"object","properties":{"amountCents":{"type":"integer","minimum":0},"currency":{"type":"string"},"termYears":{"type":"integer","exclusiveMinimum":0}},"required":["amountCents","currency"],"additionalProperties":false},"listingId":{"type":"string"},"url":{"type":"string","format":"uri"},"note":{"type":"string"}},"required":["kind","domain","provider","sourceTrust","state","listingType","checkedAt","url"],"additionalProperties":false}},"status":{"type":"string","enum":["registerable","listed","checkout_required","taken","blocked","unknown"]}},"required":["domain","offers","status"],"additionalProperties":false}}},"required":["id","label","origin","primaryDomain","domains"],"additionalProperties":false}},"diagnostics":{"type":"object","properties":{"elapsedMs":{"type":"number","minimum":0},"generatedCount":{"type":"integer","minimum":0},"evaluatedCount":{"type":"integer","minimum":0},"verifiedCount":{"type":"integer","minimum":0},"evaluationProvider":{"type":"string","enum":["jev","unavailable","not_needed"]},"deadlineReached":{"type":"boolean"},"cacheHit":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"operation":{"type":"string","enum":["check","inventory","generate","evaluate"]},"message":{"type":"string"}},"required":["provider","operation","message"],"additionalProperties":false}}},"required":["elapsedMs","generatedCount","evaluatedCount","verifiedCount","evaluationProvider","deadlineReached","issues"],"additionalProperties":false}},"required":["version","requestId","query","mode","results","diagnostics"],"additionalProperties":false}}},"x-mcp":{"transport":"streamable-http","url":"https://api.names.dev/mcp","authentication":"none"}}