{"openapi":"3.1.0","info":{"title":"Is Cited API","version":"1.0.0","description":"只读的 AI 引用就绪度报告 API。三层 pin 模型：抓取许可 / 推送就绪 / 引用形态。","contact":{"url":"https://madeinred.com","email":"hello@madeinred.com"}},"servers":[{"url":"https://madeinred.com"}],"paths":{"/api/v1/report":{"get":{"operationId":"getReport","summary":"读取最新报告","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"报告","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"URL 无效","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"尚无报告","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"限流","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/history":{"get":{"operationId":"getHistory","summary":"历次分数","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/scan":{"post":{"operationId":"scan","summary":"同步扫描并存储报告（Accept: text/event-stream 时以 SSE 推送 phase / finding / done 事件）","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"force":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"报告","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"请求无效","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"限流","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"目标不可达","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/methodology":{"get":{"operationId":"getMethodology","summary":"方法论","responses":{"200":{"description":"OK"}}}},"/api/v1/advice":{"post":{"operationId":"advice","summary":"AI 修复方案（需部署方配置模型网关）","responses":{"200":{"description":"OK"},"404":{"description":"未启用或尚无报告"}}}},"/api/v1/simulate":{"post":{"operationId":"simulate","summary":"模拟 ChatGPT 提问与引用（需部署方配置模型网关）","responses":{"200":{"description":"OK"},"404":{"description":"未启用或尚无报告"}}}},"/api/v1/hunt":{"post":{"operationId":"startHunt","summary":"信源猎手：发起一次猎捕（需登录会话或 Bearer API key；按月配额）","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["seed"],"properties":{"seed":{"type":"string","description":"细分领域 / 关键词簇 / 站点域名，3–400 字符"},"locale":{"type":"string","default":"en-GB","description":"目标市场，如 en-GB、en-US、de-DE"}}}}}},"responses":{"202":{"description":"已受理，后台运行 20–40 分钟","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"phase":{"type":"string"},"url":{"type":"string"},"poll":{"type":"string"}}}}}},"401":{"description":"未登录","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"配额或频率超限","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/hunt/{id}":{"get":{"operationId":"getHunt","summary":"猎捕状态 / 报告（进行中只返回进度，完成后返回完整报告；?full=1 强制完整）","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}}],"responses":{"200":{"description":"状态或报告","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HuntReport"}}}},"404":{"description":"不存在","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/hunt/{id}/blueprint.json":{"get":{"operationId":"getBlueprint","summary":"仿建蓝图 JSON（页面规格清单，可直接喂给写作 agent）","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"无蓝图"}}}}},"components":{"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","enum":["login_required","invalid_url","missing_url","private_target","report_not_found","rate_limit_exceeded","target_unreachable","scan_failed","bad_request","api_route_not_found","method_not_allowed","advice_disabled","advice_failed","internal_error"]},"detail":{"type":"string"},"resolution":{"type":"string"},"instance":{"type":"string"}}},"Report":{"type":"object","properties":{"target":{"type":"string"},"display_target":{"type":"string"},"report_url":{"type":"string"},"final_url":{"type":"string"},"scanned_at":{"type":"string","format":"date-time"},"score":{"type":"integer","minimum":0,"maximum":100},"raw_score":{"type":"integer"},"score_label":{"type":"string"},"gate":{"type":"object","properties":{"capped":{"type":"boolean"},"cap":{"type":"integer"},"reason":{"type":"string"}}},"score_breakdown":{"type":"object"},"findings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["crawl","push","shape","bonus"]},"name":{"type":"string"},"weight":{"type":"number"},"result":{"type":"string","enum":["passed","partial","failed","not_applicable","info"]},"credit":{"type":"number"},"details":{"type":"string"},"recommendation":{"type":"string"},"evidence":{"type":"object"}}}},"fetches":{"type":"array","items":{"type":"object"}},"preview":{"type":"object"}}},"HuntReport":{"type":"object","properties":{"id":{"type":"string"},"seed":{"type":"string"},"niche":{"type":"string"},"locale":{"type":"string"},"phase":{"type":"string","enum":["queued","questions","search","aggregate","enrich","score","dissect","blueprint","done","failed"]},"progress":{"type":"object"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"intent":{"type":"string"},"text":{"type":"string"}}}},"outcomes":{"type":"object","description":"qid → { sources, citations, answer }"},"prey":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"cited_q":{"type":"array","items":{"type":"string"}},"exclusive_q":{"type":"array","items":{"type":"string"}},"enrichment":{"type":"object"},"score":{"type":"object","properties":{"citation":{"type":"integer"},"replaceability":{"type":"integer"},"prey":{"type":"integer"},"tier":{"type":"string","enum":["A","B","watch","excluded"]},"reasons":{"type":"array","items":{"type":"string"}}}},"dissection":{"type":"object"}}}},"gap":{"type":"array","items":{"type":"object","properties":{"qid":{"type":"string"},"kind":{"type":"string","enum":["exclusive","contested","giants_only","open","unanswered"]},"small":{"type":"array","items":{"type":"string"}},"giants":{"type":"array","items":{"type":"string"}}}}},"blueprint":{"type":"object"},"stats":{"type":"object"}}}}}}