联邦公报

概览

美国联邦公报本身——谁改了什么、什么时候改、哪些还在征求意见。

状态: live
文档 id: doc_id 如 fr:2024-07332
引用格式: [89 FR 12345]

常用调用

找某机构的规则POST /v1/fr/search {"query": "PFAS drinking water", "filters": {"doc_type": "Rule"}}

正在征求意见的拟议规则

POST /v1/fr/search {"query": "出口管制 半导体", "filters": {"doc_type": "Proposed Rule", "comments_close_on": {"gte": "2026-10-09"}}}

读一篇

GET /v1/fr/read/fr:2024-07332  → 默认 level=detail（原文摘要、行为、CFR、案卷、RIN、生效/截止日期、原文链接）

是词，不是意思。这个域没有向量：mode 只有 keyword，写一句话描述需求搜不出东西——要给确切的词。支持引号短语、OR、-排除；中文会分词，中英混写会自动拆成两路。

细则

和 us_law 的分工：us_law 是现行条文（CFR / USC 条款级），fr 是公报原文（谁在什么时候改了什么）。
doc_type 用官方写法（Rule / Proposed Rule / Notice / Presidential Document / Uncategorized Document / Correction / Sunshine Act Document），小写的 rule 筛不到东西。
找正在征求意见的规则：filters.comments_close_on={"gte": "今天"}；找即将生效的：effective_on 区间。
subjects 是开放标签（模型给的），归一前不作筛选字段；要按主题筛用 fr_topics（官方主题词）。
没有向量：query 走英文 tsvector + 中文 zhparser 两路并集，中英混合会自动拆开，支持引号短语 / OR / -排除。
模型写的字段（做摘要可以，别当原文引用）：action_kind、affected、key_point、one_liner、one_liner_zh、subjects。
字段表与枚举值由库的自描述（search.field）生成，不是手写的；枚举计数的口径是 2026-10-13。

检索

POST/v1/fr/search

混合检索，每条命中一张卡片。2 credits。免费样例：PFAS drinking water。

过滤字段

字段	类型 · op	含义
action_kind	keyword · eq anyinformation_collection · meeting_or_hearing · amendment · approval_or_authorization · determination_or_finding · other …共 19 个，/facets 可列全	行为类型（闭集 19 类，模型判定）
agencies	keyword · eq any	发布机构（可多选，任一命中）
doc_type	keyword · eq anyNotice · Rule · Proposed Rule · Uncategorized Document · Presidential Document · Correction · Sunshine Act Document	文种（注意是官方写法，首字母大写：Rule / Proposed Rule / Notice / Presidential Document …）
pub_date	datetime · range	发布日期区间

还有 8 个，照样能用

字段	类型 · op	含义
cfr_refs	keyword · eq any	涉及的 CFR 条文，如 40 CFR 141
comments_close_on	datetime · range	评论截止日期区间
docket_ids	keyword · eq any	案卷号（docket）
document_number	keyword · eq any	公报文号（精确，如 2024-07332）
effective_on	datetime · range	生效日期区间
fr_topics	keyword · eq any	联邦公报官方主题词
rins	keyword · eq any	RIN（统一议程编号）
significant	bool · eq	是否 significant regulatory action

参数

参数	类型	说明
query 必填	string	1–1000 字符。也可以是最多 5 条的数组（批量，hits 变 results[]）。
top_k	integer= 10	1–200。
fields	brief · head= brief	head 多扣 1 credit，每条附 head 视图。
filters	json	过滤 DSL 对象（见快速开始）；可用字段见上表。
mode	keyword= keyword	这个域只有一种模式——词面匹配，不是语义检索。
sort	relevance · date · pub_date= relevance	结果排序。
offset	integer= 0	翻页。

示例

{ "domain": "fr", "query": "…", "hits": [ { "id": "fr:2024-07332", "score": 0.83, "brief": { … } } ], "total": null, "coverage": …, "warnings": [],
  "meta": { "request_id": "req_…", "credits": { "charged": 2, "balance": 1998, "pool": "allowance" }, "latency_ms": 41, "cached": false } }

用了未声明的过滤字段返回 400，不会静默忽略。过滤条件是 AND；可用 _or / _not。

读

GET/v1/fr/read/{doc_id}

三档深浅，不传就是 detail。免费样例：fr:2024-07332。

三档

深浅	credits	返回
brief	1	卡片：action_kind、agencies、citation、doc_id、doc_type、html_url、one_liner、one_liner_zh…
detail （默认）	2	全部结构化字段（卡片 + 原文摘要 / 明细字段）

参数

参数	类型	说明
doc_id (path) 必填	string	文档 id（doc_id）。
level	brief · detail= detail	读多深。
format	json · md · html= json	响应形态。

示例

{ "domain": "fr", "id": "fr:2024-07332", "level": "detail", "view": "detail", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } }

旧写法 GET /v1/fr/doc/{id}?view=… 仍然可用。

批量读

POST/v1/fr/read

最多 50 个 id，同一档。查不到的 id 返回 error: "not_found"，不扣费。

参数

参数	类型	说明
ids 必填	string[]	文档 id 列表。
level	brief · detail= detail	所有 id 共用的档。

示例

{ "domain": "fr", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } }

Facets

GET/v1/fr/facets?field={field}

某个过滤字段的合法值，agent 不用猜；预聚合字段带计数，声明的枚举没有。免费、不需要 key。

参数

参数	类型	说明
field 必填	action_kind · doc_type	有 facets 的过滤字段。
limit	integer= 50	最多返回多少个值。

示例

{ "domain": "fr", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } }

问registered key+ /stream

POST/v1/fr/ask

本域的 agentic 问答：没有向量层，模型把问题翻成结构化筛选 + 中英分词全文检索，读详情后作答，引用写成 [fr: <标题>]；/stream 为 NDJSON，answer_delta 是边生成边发的真实片段。effort low / medium / high 对应 50 / 100 / 200 credits。加 /stream 走 NDJSON，第一个事件一定是 billing。首个 answer_delta 之前失败会退款。

参数

参数	类型	说明
query 必填	string	1–2000 字符。问得具体；要数字就直接问数字。
effort	low · medium · high= low	检索轮数，也决定价格：50 / 100 / 200 credits。套餐限制最高档。
verbose	bool= false	返回工具调用轨迹（流式时多 tool_call / tool_result / thinking 事件）。
top_k	integer= 10	预取候选数。
stream_answer	bool= true	仅流式：false 时只发一个 answer 事件。
max_rounds	integer	0–8，覆盖 effort 预设。
force_answer_after	number	秒；强制切入作答阶段。
max_answer_tokens	integer= 4096	触顶时置 answer_truncated。
language	string	回答语言，默认跟随 query。

示例

{ "answer": "… [89 FR 12345] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } }

引用是真的——answer 里的每个 id 都存在于本垂域（格式 [89 FR 12345]）。sources 是召回集，不是引用列表。answer_truncated 表示不完整。