API 参考 / market-snapshots

市场快照证据只读（主产品引用）

GET /api/v1/market-snapshots/{snapshotId}/evidence · listMarketSnapshotEvidence

跨面契约端点：返回指定市场快照钉定的 approved Evidence 集合，供用户侧方向生成与 OnePage 证据引用。只读：不暴露原始抓取凭据、未审核数据或 research 管理动作。给定 marketSnapshotId 重放同一证据集合（快照钉定 Evidence IDs + 字典/本体版本，不受后续更新影响）。可按重复 evidenceId 精确选取引用，并按 metricKey / region / gameKey 过滤。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

参数

snapshotId（必填）: string
metricKey: string
region: string
gameKey: string
evidenceId: array
limit: integer

响应字段 · 200

snapshotId（必填）: string
weekKey（必填）: string
metricVersions: object —— 快照钉定的字典版本（复现用）
ontologyVersions: object —— 快照钉定的本体版本
items（必填）: MarketSnapshotEvidenceItem[]
items[].id（必填）: string
items[].evidenceKind（必填）: enum —— metric 是结构化观测值；claim 是带出处的内容主张。本期 Claim 只锁合同，不接采集源。；取值：metric / claim
items[].metricClass（必填）: enum —— Qualifier 决定的指标类别。旧 estimated=true 迁移为 estimate；旧 estimated=false 一律为 legacy_unclassified，禁止猜成 fact，且不可进入 V2 快照。；取值：fact / signal / estimate / legacy_unclassified
items[].dataScope（必填）: enum —— 数据作用域。V1 全局市场快照只允许 public_market。；取值：public_market / tenant_first_party
items[].truthTier（必填）: enum —— 来源真值等级；等级定义由版本化 qualifier policy 管理。；取值：T0 / T1 / T2 / T3 / T4 / T5
items[].qualityStatus（必填）: enum —— 资格与质量状态。只有 qualified 且 snapshotEligible=true 的记录可成为候选成员。；取值：pending / qualified / needs_review / rejected / blocked / quarantined
items[].snapshotEligible（必填）: boolean —— 发布时的资格判定；V2 列表恒为 true
items[].source（必填）: string
items[].sourceUrl: string
items[].sourceArtifactId: string —— 血缘锚点；不包含原始响应内容
items[].gameKey: string
items[].marketGameId: string
items[].metricKey: string —— evidenceKind=metric 时必填
items[].claimKey: string —— evidenceKind=claim 时必填
items[].value（必填）: object
items[].unit: string
items[].timeWindow: string —— 观测值覆盖的明确时间窗
items[].observedAt: string
items[].region: string
items[].language: string
items[].sample: string
items[].estimated（必填）: boolean —— 兼容字段；新记录严格由 metricClass=estimate 派生
items[].confidence（必填）: number
items[].qualifierVersion: string
items[].snapshotId（必填）: string —— 钉定这条证据的快照 id（稳定复现）

错误

401：Problem 错误响应
404：Problem 错误响应

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/market-snapshots/{snapshotId}/evidence?metricKey=…&region=…" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "snapshotId": "018f3c2e-0000-7000-8000-000000000000",
  "weekKey": "示例文本",
  "items": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "evidenceKind": "metric",
      "metricClass": "fact",
      "dataScope": "public_market",
      "truthTier": "T0",
      "qualityStatus": "pending",
      "snapshotEligible": true,
      "source": "示例文本",
      "value": {},
      "estimated": true,
      "confidence": 1,
      "snapshotId": "018f3c2e-0000-7000-8000-000000000000"
    }
  ]
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引