基础约定
基础地址是 https://api.zhimahang.com。所有端点只读并要求 Bearer API key。时间参数 since/until 使用 Unix 毫秒与半开区间 [since, until)；engine 可重复；明细集合使用 limit/cursor。
元数据
GET /v1/engines
返回 12 个引擎目录，每项含稳定 id、显示名称和颜色。调用方应存 id，不要用可翻译的名称做关联键。
GET /v1/brands
返回当前密钥可访问的品牌。租户范围来自密钥，不接受 merchantId 参数；v1 密钥当前只绑定一个租户，所以响应目前是单元素数组。
提示词
GET /v1/prompts
游标分页的提示词列表；支持 category 与 q 过滤，以及通用 limit/cursor。
GET /v1/prompts/{id}
返回单条提示词，包含正文、标签、目标关键词等详情；只能读取当前密钥租户内的资源。
运行
GET /v1/runs
游标分页的运行明细；支持 engine、prompt_id、status、since、until 与 mention 过滤。列表不返回 response_text，只返回 text_len，避免正文占满批量同步载荷。
GET /v1/runs/{id}
返回单条运行详情，包含完整 response_text 与 citations。只有需要正文时再取详情，避免 N+1 式无差别下载。
可见度
GET /v1/metrics/visibility
按天与引擎返回时间序列，包含提及数、运行数与引用数。支持 since、until 与可重复 engine；未传窗口时默认最近 30×24 小时。第一个桶从 since 精确开始，每桶固定 24 小时，最后一个桶可能更短。单次窗口最多 200 个桶（200×24 小时）；超出会返回 400 invalid_time_range（param 为 since），做长周期回填时请拆成不超过 200 天的连续分段。
GET /v1/metrics/visibility/matrix
返回提示词 × 引擎矩阵，每个单元取窗口内未软删的最新一次明细结果；相同时间以较大的 run id 决胜。该端点遵循 90 天明细读模型，并返回 retention meta。
信源
GET /v1/citations
扁平引用明细，游标分页；支持 domain、engine、since、until。相同 URL 的重复出现保留为不同 position。
GET /v1/citations/domains
按域名聚合引用次数并返回 top N；可使用时间窗和 engine 缩小范围，未传窗口时默认读取保留期内最近 90 天。显式指定更早窗口时，聚合结果仍会包含来源 run 已软删的历史引用。
竞争
GET /v1/competitors
返回当前品牌配置的竞品目录，供 SoV 结果与企业主数据映射。
GET /v1/metrics/share-of-voice
返回 SoV 榜单、按引擎拆分、KPI 与落后战场；未传窗口时默认最近 30 天。口径只覆盖自家与已配置竞品，详见「数据口径」。
用量
GET /v1/usage
返回当前密钥所属租户的自然月调用量、上限与剩余量。它用于机器监控；相同数字也进入桌面客户端统一配额区。API 免费，这不是账单金额。