砝码 FAMA 文档
这里写的每一条都来自代码：路由来自契约表，状态、事件与披露项来自各自唯一的定义。文档与代码同仓同审。
目录
获取密钥
密钥由运营方签发，只存哈希，不入库、不入代码仓。
- 运营方为账户签发密钥并告知层级；原始密钥只显示一次，服务端只保存哈希。
- 调用方在每个请求带 X-API-Key: <key> 或 Authorization: Bearer <key>。
- 没有密钥的请求被拒绝（401 auth_required）；开放匿名访问的部署按 public 层处理。
层级
可见性规则只写在一处，REST 与 MCP 共用；契约门禁 检查 internal 字段不下渗。
| 层级 | 能看到的记录 | 专属路由 / 字段 |
|---|---|---|
| public | 公开记录行（public_record）：司法拍卖通道且未标 rights_tier=internal_only 的行 | 无专属；查不到的记录与不存在的记录同样答 404，接口不泄露存在性 |
| registered | 与 public 相同 | 更高的速率配额（accounts.visibility_tier 的第二档） |
| authorized | public 的全部，加上法律审查后标 sellable=true 的授权供给行 | GET /v1/observation/{period}; POST /v1/dossier |
| internal | 全部行，含 authorized_supply 与 internal_only | GET /v1/runs; GET /v1/reports; POST /v1/reports/{report_uid}/respond; GET /v1/ops/overview；字段 raw_ref、来源 source_id、覆盖接口的实体计数与层行数 |
authorized_supply 的行与任何在核验备注里标 rights_tier=internal_only 的行，在逐源法律审查将其翻为 sellable=true 之前只对 internal 可见。transaction_history 中 rights_tier 为空的行按 internal_only 处理。
响应信封
除 /v1/health 外，每个成功响应都是 {data, meta}; meta 由服务层统一生成。
- api_version
- 固定 "v1"
- service_version
- 服务版本（语义化）
- generated_at
- 响应生成时刻
- data_as_of
- 数据时点：库内 listings 的最大 updated_at
- basis
- 本响应的口径行
- tier
- 调用方被解析到的层级
- autoverify_version
- 自动核验规则版本
- request_id
- 请求标识，同时出现在响应头 X-Request-ID
错误结构
错误响应为 {"error": {"code", "message", "detail"}, "meta": {"request_id"}}，响应头带 X-Request-ID。常见 code:
| HTTP | code | 何时 |
|---|---|---|
| 401 | auth_required | 未带密钥且服务未开启匿名访问 |
| 401 | invalid_key | 密钥无法识别 |
| 403 | forbidden | 路由要求更高层级 |
| 404 | not_found | 记录不存在，或存在但本层级不可见（两者同答） |
| 422 | invalid_request | 参数无法求值（如无效的时点、空的更正内容） |
| 429 | rate_limited | 超过本层级每分钟配额；detail 含 tier 与 per_minute，响应头带 Retry-After |