{"openapi":"3.1.0","info":{"title":"IPure API","version":"1.0.0","summary":"IP 纯净度 / 风险检测：评分、代理与 VPN 判定、黑名单、分场景适用性，附逐项依据与数据边界。","description":"无需 API key。已收录的 IP 直接返回库中报告；未收录的 IP 会真实查询各数据源，每个来源 IP 每天可免验证查询 5 次（全站另有每日总量上限，剩余次数见响应头 x-open-budget-remaining），用完后返回 403 并附 reportUrl —— 在浏览器打开它完成一次检测后即可直接调用。所有结论基于查询时刻的公开与合作数据源，不构成账号安全或平台准入的保证；响应中的 unknowns 列出仅凭 IP 无法判断的事项。","contact":{"url":"https://ipure.dev/docs/api"},"x-when-to-use":"用户想知道某个 IP 是否干净、是否为代理 / VPN / 机房、能否用于 AI 服务 / 社交平台注册 / 流媒体 / 游戏平台 / 跨境电商 / 邮件发送时。","x-when-not-to-use":"DNS 配置、网络故障排查、需要目标平台内部风控数据才能回答的问题。"},"servers":[{"url":"https://ipure.dev"}],"paths":{"/api/lookup":{"get":{"operationId":"lookupIp","summary":"查询一个 IP 的完整纯净度报告","parameters":[{"name":"ip","in":"query","required":true,"schema":{"type":"string"},"description":"IPv4 或 IPv6 地址。IPv6 可用 [] 包裹；::ffff: 形式的映射地址按 IPv4 处理。","example":"8.8.8.8"},{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"忽略缓存与历史库强制重查。真实消耗数据源配额，需人机验证，每客户端 5 次 / 分钟。"}],"responses":{"200":{"description":"报告。source 字段说明它来自实时查询（fresh）、进程缓存（cache）还是历史库（store）。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"不是有效的 IP 地址","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"未收录的 IP 且免验证额度已用完（code = verification_required）。响应含 hint 与 reportUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"超过限流：普通查询 30 次 / 分钟，首次查询新 IP 10 次 / 分钟，refresh 5 次 / 分钟","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/myip":{"get":{"operationId":"myIp","summary":"回显调用方的公网 IP","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["text"]},"description":"text 时返回纯文本，便于 curl 直接取值"}],"responses":{"200":{"description":"{ ip } 或纯文本"}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"},"reportUrl":{"type":"string","format":"uri"}},"required":["error"]},"Report":{"type":"object","description":"字段释义见 /docs/api。","properties":{"ip":{"type":"string"},"version":{"type":"integer","enum":[4,6]},"queriedAt":{"type":"string","format":"date-time","description":"本次报告生成时间；store 来源时为当初检测时间"},"source":{"type":"string","enum":["fresh","cache","store"]},"stale":{"type":"boolean","description":"库中报告是否已超过陈旧阈值，建议 refresh"},"usageType":{"type":"string","enum":["residential","business","hosting","mobile","education","government","unknown"]},"nativeType":{"type":"string","enum":["native","broadcast","unknown"],"description":"原生 / 广播：注册地与使用地是否一致"},"flags":{"type":"object","properties":{"isProxy":{"type":"boolean"},"isVpn":{"type":"boolean"},"isTor":{"type":"boolean"},"isHosting":{"type":"boolean"},"isMobile":{"type":"boolean"},"isRelay":{"type":"boolean"},"isBogon":{"type":"boolean"},"isSearchEngineBot":{"type":"boolean"}}},"flagAgreement":{"type":"object","description":"各判定位有几家数据源一致确认","additionalProperties":{"type":"integer"}},"vpnOperator":{"type":["object","null"],"description":"已知商业 VPN 才有","properties":{"name":{"type":"string"},"url":{"type":"string"},"anonymity":{"type":"string"},"popularity":{"type":"string"},"protocols":{"type":"array","items":{"type":"string"}},"logging":{"type":"boolean"},"freeAccess":{"type":"boolean"}}},"geo":{"type":"object","properties":{"country":{"type":"string"},"countryName":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"},"timezone":{"type":"string"}}},"asn":{"type":"object","properties":{"asn":{"type":"integer"},"name":{"type":"string"},"org":{"type":"string"},"route":{"type":"string"}}},"registry":{"type":"object","properties":{"rir":{"type":"string"},"country":{"type":"string"},"netName":{"type":"string"},"org":{"type":"string"},"cidr":{"type":"string"}}},"risk":{"type":"object","properties":{"purity":{"type":"integer","minimum":0,"maximum":100,"description":"纯净度，越高越干净"},"level":{"type":"string","enum":["pristine","clean","neutral","suspicious","risky","dangerous"]},"label":{"type":"string"},"verdict":{"type":"string"},"confidence":{"type":"string","enum":["low","medium","high"],"description":"参与评分的数据源覆盖度，与分数分开看"},"factors":{"type":"array","description":"每一分的来源。points 为内部风险点数：正数扣纯净度，负数加回","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"category":{"type":"string"},"points":{"type":"number"},"detail":{"type":"string"},"floor":{"type":"number"}}}}}},"scenarios":{"type":"array","description":"分场景适用性（AI 服务 / 社交平台注册 / 流媒体 / 游戏平台 / 跨境电商 / 邮件发送）","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"score":{"type":"integer"},"level":{"type":"string","enum":["excellent","good","fair","poor","unusable","restricted"]},"levelLabel":{"type":"string"},"reason":{"type":"string"}}}},"blocklists":{"type":"array","items":{"type":"object","properties":{"zone":{"type":"string"},"label":{"type":"string"},"listed":{"type":"boolean"},"benign":{"type":"boolean","description":"命中但不构成风险（如 Spamhaus PBL 的住宅段声明）"},"unavailable":{"type":"boolean","description":"该名单本次不可用，命中与否未知"}}}},"abuse":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"score":{"type":"integer"},"reports":{"type":"integer"},"attacks":{"type":"object","properties":{"total":{"type":"integer"},"byType":{"type":"object","additionalProperties":{"type":"integer"}}}}}}},"exposure":{"type":["object","null"],"properties":{"observed":{"type":"boolean"},"ports":{"type":"array","items":{"type":"integer"}},"vulns":{"type":"array","items":{"type":"string"}}}},"sharing":{"type":["object","null"],"properties":{"address":{"type":"integer"},"subnet":{"type":"integer"}}},"sources":{"type":"array","description":"各数据源本次的状态。ok=false 表示失败，不等于未命中","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["free","commercial"]},"ok":{"type":"boolean"},"ms":{"type":"integer"},"error":{"type":"string"},"skipped":{"type":"string"}}}},"feedback":{"type":"object","description":"实测反馈：正在用这个 IP 的访客给各场景打的真实使用体验分。键为场景 id，某场景满 3 人才出现。独立于评分。","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"average":{"type":"number","minimum":1,"maximum":5,"description":"1-5，5 最好（很顺 5 · 能用 4 · 勉强 3 · 常被拦 2 · 不能用 1）"}}}},"reportUrl":{"type":"string","format":"uri","description":"这份报告的网页地址，引用结论时请附上"},"unknowns":{"type":"array","description":"仅凭 IP 无法判断的事项","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"detail":{"type":"string"}}}}},"required":["ip","version","queriedAt","source","usageType","nativeType","flags","risk","scenarios","sources"]}}}}