{"openapi":"3.1.0","info":{"title":"names.dev naming and shared shortlists","version":"2.3.0","description":"Public naming and domain evidence, plus explicitly shared capability-protected shortlists. No purchase, seller write or private-account operations. Amounts are USD cents unless an evidence price specifies a different currency."},"servers":[{"url":"https://api.names.dev"}],"security":[],"paths":{"/api/v1/marketplace/lots":{"get":{"servers":[{"url":"https://names.dev"}],"operationId":"names_portfolio_search","summary":"Find published domain portfolios sold as whole lots","description":"Read-only public catalog of control-checked portfolios. Asking prices cover every domain together. Payment and transfer remain not_recorded; offers and agreements require a person to review the source page.","parameters":[{"in":"query","name":"q","schema":{"type":"string","maxLength":80}},{"in":"query","name":"max_price_usd","description":"Whole-portfolio USD asking-price ceiling, expressed in dollars rather than cents.","schema":{"type":"string","pattern":"^[0-9]+(?:\\.[0-9]{1,2})?$"}},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"maximum":500,"default":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":20,"default":12}}],"responses":{"200":{"description":"Published portfolio lots, with explicit whole-lot price scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioCatalog"}}}},"400":{"description":"Invalid filter or pagination."},"429":{"description":"Wait before retrying."},"503":{"description":"Inventory could not be confirmed. This is not an empty catalog."}}}},"/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. Explicit excludeLabels apply to alternatives before ranking and the result limit; requested exact or seed names remain visible. A brief's likedNames steer its alternatives toward their construction and register on other roots, never their marks, and dislikedLabels leave out each name's family (its root or ending); exact-domain and label searches ignore both. 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."}}}},"/v2/shortlists":{"post":{"operationId":"shortlist_create","summary":"Explicitly create an unlisted shared shortlist","description":"Stores reviewed brief/preferences and selected domains, not availability or price claims. Uses one search allowance. Read and owner edit/revocation capabilities are distinct; only hashes are persisted. Expires after 30 days. Keep editToken private and put only readToken in the human share URL fragment.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortlistRequest"}}}},"responses":{"201":{"description":"Reader capability and separate owner revocation capability. Human URL: https://names.dev/shortlists/{id}#{readToken}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortlistCreated"}}}},"400":{"description":"Invalid title, brief, domains or preferences; fabricated evidence is rejected."},"413":{"description":"Body exceeds 16 KiB."},"429":{"description":"Shared public allowance exhausted."},"503":{"description":"Shortlist storage or limiting unavailable."}}}},"/v2/shortlists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"shortlist_read","summary":"Read an unlisted shared shortlist","description":"Authenticate using the reader capability in the Authorization header, never a token query parameter. Does not return capability values/hashes or live availability. Use a fresh domain check for current evidence.","security":[{"ShortlistReadCapability":[]}],"responses":{"200":{"description":"Selected domains, original brief/preferences and timestamps, without owner capabilities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortlistResponse"}}}},"404":{"description":"Absent, malformed, wrong, expired and revoked access are indistinguishable."},"503":{"description":"Shortlist storage unavailable."}}},"delete":{"operationId":"shortlist_revoke","summary":"Revoke shortlist sharing","description":"Only at the user's request. Requires the distinct private owner edit/revocation capability. A reader capability cannot revoke. Owner capability is never put in share links or read responses.","security":[{"ShortlistOwnerCapability":[]}],"responses":{"200":{"description":"Sharing revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"const":true}},"required":["revoked"],"additionalProperties":false}}}},"404":{"description":"Absent, wrong, reader-only, expired and revoked access are indistinguishable."},"503":{"description":"Shortlist storage unavailable."}}}}},"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, si or co.uk, in preference order. Unsupported registrar checks remain unknown; real marketplace listings may still be returned."},"budgetMaxUsdCents":{"type":"integer","minimum":0,"maximum":1000000000000,"description":"Maximum acquisition budget in USD cents; $500 is 50000. Prices remain provider observations."},"excludeLabels":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"},"maxItems":48,"description":"Explicitly rejected alternative labels, scoped to this brief; up to 48. Requested exact names are still checked."},"likedNames":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"},"meaning":{"type":"string","maxLength":240}},"required":["label"],"additionalProperties":false},"maxItems":8,"description":"Names the user saved for this brief, most recent first, up to 8, each with its meaning. New names follow their construction and register on other roots and never repeat their mark. Brief searches only; exact domains and bare labels ignore them."},"dislikedLabels":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"},"maxItems":48,"description":"Names the user turned down for this brief, up to 48. New names avoid each one's family: the same root or the same ending. Brief searches only; requested names are still checked."}},"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","description":"The evidenced acquisition domain. It can be a get/try prefix or app suffix variant of label; never imply the exact matching domain is available."},"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"]},"evaluationModel":{"type":"string","maxLength":100},"inventorySources":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","maxLength":100},"retrieved":{"type":"integer","minimum":0},"reviewed":{"type":"integer","minimum":0},"shortlisted":{"type":"integer","minimum":0}},"required":["provider","retrieved","reviewed","shortlisted"],"additionalProperties":false},"maxItems":20},"deadlineReached":{"type":"boolean"},"cacheHit":{"type":"boolean"},"screenedOut":{"type":"integer","minimum":0},"brands":{"type":"object","properties":{"vetoed":{"type":"integer","minimum":0},"flagged":{"type":"integer","minimum":0}},"required":["vetoed","flagged"],"additionalProperties":false},"offBrief":{"type":"integer","minimum":0},"overuse":{"type":"object","properties":{"marks":{"type":"integer","minimum":0},"keptOut":{"type":"integer","minimum":0}},"required":["marks","keptOut"],"additionalProperties":false},"stageMs":{"type":"object","properties":{"check":{"type":"integer","minimum":0},"gather":{"type":"integer","minimum":0},"review":{"type":"integer","minimum":0},"verify":{"type":"integer","minimum":0},"recovery":{"type":"integer","minimum":0},"screen":{"type":"integer","minimum":0},"fit":{"type":"integer","minimum":0}},"additionalProperties":false},"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},"PortfolioCatalog":{"type":"object","properties":{"format":{"type":"string","const":"names.dev/portfolio-catalog/v1"},"priceScope":{"type":"string","const":"whole_portfolio"},"lots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,58}[a-z0-9])?$"},"title":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":2000},"status":{"type":"string","const":"live"},"availableForAgreement":{"type":"boolean","const":true},"priceScope":{"type":"string","const":"whole_portfolio"},"saleMode":{"type":"string","const":"all_or_nothing"},"askingPrice":{"anyOf":[{"type":"object","properties":{"amountCents":{"type":"integer","exclusiveMinimum":0,"maximum":10000000000},"currency":{"type":"string","const":"USD"}},"required":["amountCents","currency"],"additionalProperties":false},{"type":"null"}]},"mode":{"type":"string","enum":["make_offer","buy_now","buy_now_or_offer"]},"revision":{"type":"integer","exclusiveMinimum":0},"domainCount":{"type":"integer","minimum":2,"maximum":100},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","maxLength":253,"pattern":"^[a-z0-9-]+(?:\\.[a-z0-9-]+)+$"},"displayDomain":{"type":"string","minLength":1,"maxLength":253},"controlCheckedAt":{"type":"string","format":"date-time"},"controlMethod":{"type":"string","enum":["dns_txt","registrar_api"]}},"required":["domain","displayDomain","controlCheckedAt","controlMethod"],"additionalProperties":false},"minItems":2,"maxItems":100},"humanApprovalRequired":{"type":"boolean","const":true},"paymentStatus":{"type":"string","const":"not_recorded"},"transferStatus":{"type":"string","const":"not_recorded"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","slug","title","description","status","availableForAgreement","priceScope","saleMode","askingPrice","mode","revision","domainCount","domains","humanApprovalRequired","paymentStatus","transferStatus","updatedAt"],"additionalProperties":false},"maxItems":20},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1,"maximum":500},"limit":{"type":"integer","minimum":1,"maximum":20},"hasMore":{"type":"boolean"}},"required":["format","priceScope","lots","total","page","limit","hasMore"],"additionalProperties":false},"ShortlistRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"brief":{"type":"string","maxLength":2000},"domains":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":8},"tlds":{"type":"array","items":{"type":"string","minLength":2,"maxLength":40,"pattern":"^\\.?[a-z0-9-]+(?:\\.[a-z0-9-]+)*$"},"maxItems":12},"budgetMaxUsdCents":{"type":"integer","minimum":0,"maximum":1000000000000}},"required":["title","brief","domains"],"additionalProperties":false},"ShortlistCreated":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"},"readToken":{"type":"string","pattern":"^[a-f0-9]{64}$"},"editToken":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","readToken","editToken","expiresAt"],"additionalProperties":false},"ShortlistResponse":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"brief":{"type":"string","maxLength":2000},"domains":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":8},"tlds":{"type":"array","items":{"type":"string","minLength":2,"maxLength":40,"pattern":"^\\.?[a-z0-9-]+(?:\\.[a-z0-9-]+)*$"},"maxItems":12},"budgetMaxUsdCents":{"type":"integer","minimum":0,"maximum":1000000000000},"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"evidence":{"type":"string","const":"check_domains_for_current_evidence"},"access":{"type":"string","const":"unlisted_link"}},"required":["title","brief","domains","id","createdAt","expiresAt","evidence","access"],"additionalProperties":false}},"securitySchemes":{"ShortlistReadCapability":{"type":"http","scheme":"bearer","bearerFormat":"opaque-64-hex","description":"Reader capability returned by creation or carried in the human share URL fragment. No account or Rufio credential."},"ShortlistOwnerCapability":{"type":"http","scheme":"bearer","bearerFormat":"opaque-64-hex","description":"Distinct private editToken from creation, used only for revocation. Never share this value with readers."}}},"x-mcp":{"transport":"streamable-http","url":"https://api.names.dev/mcp","authentication":"none"}}