{"openapi":"3.1.0","info":{"title":"NamePico","version":"1.3.0","description":"域名与品牌证据层。查一个域名能不能注册、注册商是否给出报价，以及已覆盖的公开风险证据：注册状态、各渠道价格、注册局政策风险、滥用度、历史使用记录、黑名单、同名占用，给出 0-100 的综合判定。也支持批量核验一批名字的注册状态（/api/v1/domains/check），以及按严格字母重合生成候选名（/api/v1/names/overlap）。每条判据都标明性质（事实 / 推断 / 人工档案 / 启发式）与数据源。免费，无需 API key。结论的边界见 https://staging.namepico.com/llms.txt 的「看不到什么」一节 —— 转述结论时请一并说明。","contact":{"url":"https://staging.namepico.com/feedback"}},"externalDocs":{"url":"https://staging.namepico.com/developers","description":"MCP 与接口总览（含证据语义、调用顺序和限流）"},"servers":[{"url":"https://staging.namepico.com"}],"paths":{"/api/d/{domain}":{"get":{"operationId":"getDomainReport","summary":"单个域名的完整评估报告","description":"返回注册状态、综合判定与全部判据、各渠道价格、历史、黑名单、同名占用、分用途结论，以及 unknowns（本次没查到的事项）。域名后面加 .txt 可得同一份报告的纯文本版，例如 /api/d/example.com.txt —— 不用解析 JSON 就能读。品牌证据的 exact_string 只表示 matchedField 中出现 matchedText，不等于精确品牌名命中；还需读取 isStandaloneEntity 与 isBrandNameMatch。execution.complete 只表示计划查询结束，no_match 也不证明不存在冲突，应同时读取 coverage 与 conclusion。similarDomainEvidence 只报告有限变体的注册局与网页事实，不表示同业或侵权；websiteObservation 与 registryStatus 相互独立。规范证据字段为 brandEvidence，兼容字段按 evidenceId 去重。注意：status 为 unknown 时不等于「可注册」；已注册或注册局保留的域名不会给出购买建议。","parameters":[{"name":"domain","in":"path","required":true,"description":"带后缀的完整域名，如 example.com。加 .txt 后缀返回纯文本。","schema":{"type":"string"},"example":"ipure.dev"}],"responses":{"200":{"description":"报告（JSON；路径以 .txt 结尾时为 text/plain）"},"400":{"description":"域名格式不对，或只给了名字没给后缀（请改用 /api/n/{name}）"},"429":{"description":"超出限流：每分钟 8 次、每小时 30 份报告。响应头 retry-after 给出等待秒数。"}}}},"/api/n/{name}":{"get":{"operationId":"getSuffixMatrix","summary":"一个名字在十几个常用后缀下的对比","description":"返回每个后缀下的注册状态、价格与后缀层面的判定，以及推荐的首选。这一层只看后缀，域名自己的历史、黑名单与同名占用要用 /api/d/{domain} 逐个查。","parameters":[{"name":"name","in":"path","required":true,"description":"不带后缀的名字，如 example","schema":{"type":"string"},"example":"ipure"}],"responses":{"200":{"description":"后缀矩阵（JSON）"},"400":{"description":"传了带后缀的域名（请改用 /api/d/{domain}）"},"429":{"description":"超出限流"}}}},"/report/{domain}":{"get":{"operationId":"getDomainReportAlt","summary":"同 /api/d/{domain}，默认返回纯文本","description":"和 /api/d/{domain} 返回同一份数据，区别只有两点：路径里不带 /api/，默认给纯文本。加 .json 得 JSON，加 .txt 仍是纯文本。**取数工具读不到 /api/ 开头的地址时改用这个。**","parameters":[{"name":"domain","in":"path","required":true,"description":"带后缀的完整域名；可加 .json 或 .txt 指定格式","schema":{"type":"string"},"example":"ipure.dev"}],"responses":{"200":{"description":"报告（默认 text/plain；路径以 .json 结尾时为 JSON）"},"400":{"description":"域名格式不对"},"429":{"description":"超出限流"}}}},"/matrix/{name}.json":{"get":{"operationId":"getSuffixMatrixAlt","summary":"同 /api/n/{name}，路径里不带 /api/","parameters":[{"name":"name","in":"path","required":true,"description":"不带后缀的名字","schema":{"type":"string"},"example":"ipure"}],"responses":{"200":{"description":"后缀矩阵（JSON）"},"429":{"description":"超出限流"}}}},"/api/v1/domains/check":{"post":{"operationId":"checkDomainsBatch","summary":"批量核验注册状态（可选价格），不触发深度报告","description":"一次最多 20 个名字 × 3 个后缀，或最多 60 个完整域名。只查 RDAP 注册状态，不查历史、黑名单、同名站点这些慢源。include_price 为 true 时，只对可注册的域名按域名向注册商要报价，单次最多 10 个。status=unknown 不等于可注册；price.state=unverified 不等于标准价。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCheckRequest"},"examples":{"names":{"summary":"名字 × 后缀","value":{"names":["investudy","valuemind"],"tlds":["com"]}},"domains":{"summary":"完整域名 + 价格核验","value":{"domains":["investudy.com","valuemind.io"],"include_price":true}}}}}},"responses":{"200":{"description":"每个域名的状态；单项失败也在 results 里，error 字段说明原因","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCheckResponse"}}}},"400":{"description":"请求体不合法、超过上限，或没有任何合法域名"},"429":{"description":"超出批量配额；retry-after 给出等待秒数"}}}},"/check/{domains}":{"get":{"operationId":"checkDomainsBatchAlt","summary":"同 /api/v1/domains/check 的 GET 路径别名（只查状态）","description":"给不能 POST、也不能带查询参数的 Agent 用。逗号分隔，最多 20 个完整域名。默认返回 text/plain；加 .json 得 JSON。价格核验请用 POST。","parameters":[{"name":"domains","in":"path","required":true,"description":"逗号分隔的完整域名；可加 .json 或 .txt","schema":{"type":"string"},"example":"investudy.com,valuemind.io"}],"responses":{"200":{"description":"纯文本表格；.json 结尾时为 BatchCheckResponse"},"400":{"description":"域名不合法，或超过 20 个"},"429":{"description":"超出批量配额"}}}},"/api/v1/names/overlap":{"post":{"operationId":"generateOverlapNames","summary":"按严格字母重合生成候选名字","description":"A 的非空后缀与 B 的前缀完全相同，去掉重复段后拼接（invest + study → investudy）。没有重合就不生成，不会把自由融合谎称 overlap。只做规则，不做语义或品牌判断。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverlapRequest"},"example":{"roots":["invest","study"],"min_length":6,"max_length":9,"min_overlap":2}}}},"responses":{"200":{"description":"候选列表；没有候选时 note 会说明可调的方向","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverlapResponse"}}}},"400":{"description":"roots 缺失或类型不对"},"429":{"description":"超出限流"}}}},"/names/overlap/{roots}":{"get":{"operationId":"generateOverlapNamesAlt","summary":"同 /api/v1/names/overlap 的 GET 路径别名","description":"词根用逗号分隔，使用默认参数（长度 6–9、最小重合 2）。默认纯文本，加 .json 得 JSON。","parameters":[{"name":"roots","in":"path","required":true,"description":"逗号分隔的词根；可加 .json 或 .txt","schema":{"type":"string"},"example":"invest,study"}],"responses":{"200":{"description":"纯文本候选列表；.json 结尾时为 OverlapResponse"},"400":{"description":"词根缺失"},"429":{"description":"超出限流"}}}},"/llms.txt":{"get":{"operationId":"getAgentGuide","summary":"写给 AI Agent 的说明：能回答什么、看不到什么、什么时候该调用","responses":{"200":{"description":"text/plain"}}}}},"components":{"schemas":{"BatchCheckRequest":{"type":"object","description":"names + tlds 与 domains 二选一。names 里自带后缀的项按它写的来，不再乘 tlds。","properties":{"names":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"不带后缀的名字"},"tlds":{"type":"array","items":{"type":"string"},"maxItems":3,"default":["com"]},"domains":{"type":"array","items":{"type":"string"},"maxItems":60,"description":"完整域名"},"include_price":{"type":"boolean","default":false,"description":"对可注册域名查报价，单次最多 10 个"},"force":{"type":"boolean","default":false,"description":"跳过十分钟缓存重新核验"}}},"BatchCheckResponse":{"type":"object","properties":{"checkedAt":{"type":"string","format":"date-time"},"durationMs":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchResult"}},"errors":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"reason":{"type":"string"}}}},"notes":{"type":"array","items":{"type":"string"},"description":"本次核验的边界与未做事项"}}},"BatchResult":{"type":"object","properties":{"domain":{"type":"string"},"name":{"type":"string"},"tld":{"type":"string"},"status":{"type":"string","enum":["available","registered","reserved","unknown"]},"source":{"type":"string","description":"rdap / dns / batch"},"checkedAt":{"type":"string","format":"date-time"},"error":{"type":"string","description":"unknown 时的原因；不等于可注册"},"registration":{"type":"object","description":"RDAP 返回的注册信息（注册商、日期、状态码等）"},"suspended":{"type":"boolean"},"dropping":{"type":"boolean"},"suffixPrice":{"type":"object","description":"后缀标准价，不是这个域名的报价","properties":{"register":{"type":"number"},"renew":{"type":"number"},"source":{"type":"string"}}},"price":{"type":"object","properties":{"state":{"type":"string","enum":["not_applicable","unverified","standard","premium","reserved_suspect"]},"reason":{"type":"string","description":"unverified 时的原因"},"source":{"type":"string","description":"实际提供域名报价的注册商"},"currency":{"type":"string","enum":["USD"]},"register":{"type":"number"},"renew":{"type":"number"},"checkedAt":{"type":"string","format":"date-time","description":"域名报价实际检查时间"},"quoteType":{"type":"string","enum":["live","cached"]},"taxIncluded":{"type":["boolean","null"],"description":"null 表示注册商未说明税费"},"renewPremium":{"type":"boolean"},"text":{"type":"string","description":"可直接转述的一句话"}}},"buyUrls":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"kind":{"type":"string","enum":["registrar_search","checkout"]}}}},"pageUrl":{"type":"string","description":"完整评估页"}}},"OverlapRequest":{"type":"object","required":["roots"],"properties":{"roots":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"词根，逗号/空格分隔的字符串或字符串数组；最多 8 个"},"min_length":{"type":"integer","default":6},"max_length":{"type":"integer","default":9},"min_overlap":{"type":"integer","default":2,"description":"严格重合的最小字母数"},"max_results":{"type":"integer","default":200}}},"OverlapResponse":{"type":"object","properties":{"roots":{"type":"array","items":{"type":"string"}},"candidates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"strategy":{"type":"string","const":"overlap"},"parts":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2},"overlap":{"type":"string"},"k":{"type":"integer"},"length":{"type":"integer"},"score":{"type":"number","description":"可解释启发式：重合长度、总长度、可发音性"},"explanation":{"type":"string"}}}},"errors":{"type":"array","items":{"type":"string"}},"note":{"type":"string"},"total":{"type":"integer"}}}}}}