法律
概览
二十多个法域的法规,按条检索,带译文与条级抽取。
- 状态
- live
- 文档 id
law_id如刑法- 引用格式
[中华人民共和国刑法 第266条]
常用调用
找法条
POST /v1/law/search {"query": "刑法第266条"} → 法名+条号直接定位;也可以写问题 "网络诈骗怎么判"读一条
GET /v1/law/read/<检索结果的 id> → id 形如 chn:law:中华人民共和国刑法~296,默认读这一条(原文 + 中英译 + 抽取);level=full 连前后条读一部法
GET /v1/law/read/刑法 → 默认 level=detail:摘要、章节、关键条款;全文 level=full(分页),一章 level=full§ion=<章 id>法条 + 判例一起问
POST /v1/law/ask {"query": "网络刷单诈骗未遂一般怎么判", "effort": "low"}覆盖到哪,差在哪。刑事判决已齐,民事也补灌完了,但相对公开出来的全部裁判文书,这仍是其中一部分,而且进来的顺序跟着 enrichment 队列走,不是随机抽的。每个 Law / Cases 响应都带 coverage,把里面的 note 抄进 agent 的 tool description,结论就会带上该有的限定。
翻页到 1000 为止。Law 与 Cases 的 offset + top_k 不能超过 max_window,超了返回 400。要更多结果,用筛选收窄,而不是往后翻。美国判决意见里不在向量层的那部分(tier=b)只能按关键词检索。
法条能找到判例,判例也能找回法条。每份判决的法律依据都归一成 CN/刑法/266 这样的 law_refs。由法条找判例用 extra=cases,由判例回到法条用 extra=laws。
细则
- law_id 接受 doc_id(jpn:law:労働基準法)或中文法名/简称(刑法、劳动合同法)。
- query 里写「刑法第266条」这种法名+条号会先走精确定位。
- 默认 scope=national,不含地方法规(地方法规大量复制国家法条文,是最大干扰源)。
- 译文与抽取都是模型生成,引用以原文 text.src 为准;needs_review=true 的条译文长度异常。
- level=brief / detail 里的 knowledge_fill 是模型凭常识补的元数据,不是原文依据。
检索
POST
/v1/law/search混合检索,每条命中一张卡片。2 credits。免费样例:
诈骗罪 量刑。过滤字段
| 字段 | 类型 · op | 含义 |
|---|---|---|
| jurisdiction | keyword · eq anyCHN · JPN · GBR · USA · DEU · KOR …共 26 个,/facets 可列全 | ISO3,如 CHN / JPN / GBR / USA / DEU / KOR;可多选 |
| law_id | keyword · eq | 限定一部法:doc_id 或中文法名/简称 |
| status | keyword · eq anyin_force · repealed · not_yet · unknown | in_force / repealed / not_yet / unknown |
还有 6 个,照样能用
| 字段 | 类型 · op | 含义 |
|---|---|---|
| scope | keyword · eqnational · all · local | national(默认,不含地方法规)/ all / local |
| granularity | keyword · eqarticle · law | article(默认,条级命中)/ law(部级:这个问题该查哪部法) |
| law_type | keyword · eq anyact · code · regulation · ordinance · decree · judicial_interpretation · constitution · other | 法规类型 |
| domain | keyword · eq any | 法律领域(domain_global id,见 facets) |
| norm_type | keyword · eq anyprocedure · obligation · scope · permission · prohibition · penalty · definition · right · principle | 规范类型:obligation / prohibition / penalty / permission / procedure / definition / scope …(见 facets) |
| effective_at | datetime · range | 生效日期区间 |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–1000 字符。也可以是最多 5 条的数组(批量,hits 变 results[])。 |
| top_k | integer= 10 | 1–100。 |
| fields | brief · head= brief | head 多扣 1 credit,每条附 head 视图。 |
| filters | json | 过滤 DSL 对象(见快速开始);可用字段见上表。 |
| mode | hybrid · dense · bm25= hybrid | 检索模式。不传就用第一个。 |
| offset | integer= 0 | 翻页。 |
示例
{ "domain": "law", "query": "…", "hits": [ { "id": "刑法", "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。检索结果的 id 可以直接拿去读:条文命中的 id 形如
<law_id>~<n>(如 chn:law:中华人民共和国刑法~296),GET /v1/law/doc/<hit.id> 读到的就是这一条,不用自己拆出法名再传 article。(原来用 #,在 URL 里是锚点会被截掉。)读
GET
/v1/law/read/{law_id}三档深浅,不传就是
detail。免费样例:刑法。三档
| 深浅 | credits | 返回 |
|---|---|---|
| brief | 1 | 一部法的卡片:三语标题、机关、类型、层级、状态、日期、一句话、领域、条数 |
| detail (默认) | 2 | brief + 摘要、章节树(每章一句)、关键条款、术语表、义务/罚则、典型问题、路由提示(~1–3k tok) |
| full | 5 | 全文,按条分页(offset / limit;看 truncated / next_offset) |
侧面
同一份文档的另一个侧面,与 level 二选一。
| 侧面 | credits | 返回 |
|---|---|---|
| cases | 2 | 法条 → 引用它的判决:引用计数 + 列表(给 query 按相关性排,否则按年份倒序) |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| law_id (path) 必填 | string | 文档 id(law_id)。 |
| level | brief · detail · full= detail | 读多深。 |
| extra | cases | 改读某个侧面,与 level 二选一。 |
| format | json · md · html= json | 响应形态。 |
| offset | integer= 0 | (level = full) |
| limit | integer= 200 | (level = full) |
| section_id | string | 章 id,见 level=detail 的 structure (level = full:只读这一节) |
| article | string | id 是检索结果的 law_id~n 时不用给 (extra = cases) |
| query | string | (extra = cases) |
| nature | string= all | criminal | civil | all (extra = cases) |
| top_k | integer= 10 | (extra = cases) |
示例
{ "domain": "law", "id": "刑法", "level": "detail", "view": "head", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } 检索结果可以直接读。
law_id~n 这样的 id 就是一条法条,三档也跟着收窄:卡片、这一条(原文 + 译文 + 抽取)、连同上下文。旧写法
GET /v1/law/doc/{id}?view=… 仍然可用。批量读
POST
/v1/law/read最多 50 个 id,同一档。查不到的 id 返回
error: "not_found",不扣费。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| ids 必填 | string[] | 文档 id 列表。 |
| level | brief · detail · full= detail | 所有 id 共用的档。 |
| extra | cases | 改读某个侧面。 |
示例
{ "domain": "law", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
GET
/v1/law/facets?field={field}某个过滤字段的合法值,agent 不用猜;预聚合字段带计数,声明的枚举没有。免费、不需要 key。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| field 必填 | jurisdiction · law_type · status · domain · norm_type | 有 facets 的过滤字段。 |
| limit | integer= 50 | 最多返回多少个值。 |
示例
{ "domain": "law", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } 问registered key+ /stream
POST
/v1/law/ask法条 + 判决联合 agentic 问答:先找依据条文、读原文,再看同类判决怎么判;回答带 [法名 第N条] / [案号] 引用,多 sources.laws / sources.cases / coverage。
effort low / medium / high 对应 50 / 100 / 200 credits。加 /stream 走 NDJSON,第一个事件一定是 billing。首个 answer_delta 之前失败会退款。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–2000 字符。问得具体;要数字就直接问数字。 |
| scope | auto · law · case · both= auto | 只查法条 / 只查判决 / 都查 |
| jurisdiction | string | ISO3,默认不限(模型按问题判断) |
| 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": "… [中华人民共和国刑法 第266条] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } 回答里可能出现人名。判决正文要
cases:fulltext 授权,但它读的抽取字段不需要,而当事人姓名就在抽取字段里——所以答案里可能带着自然人姓名。拿到的内容按个人信息对待。引用是真的——
answer 里的每个 id 都存在于本垂域(格式 [中华人民共和国刑法 第266条])。sources 是召回集,不是引用列表。answer_truncated 表示不完整。案例
中国判决书:刑事已齐,民事补灌也完成了。相对公开出来的全部裁判文书,这仍是其中一部分,每个响应都用 coverage 说清楚。
- 状态
- live
- 文档 id
uuid如8a1c3791-0cce-4094-9b28-a9a600b657c7- 引用格式
[(2018)闽0181刑初1319号]
常用调用
找判例
POST /v1/cases/search {"query": "网络刷单诈骗 未遂", "filters": {"province": "浙江省", "judge_year": {"gte": 2018}}}读一份判决
GET /v1/cases/read/<uuid> → level=detail(默认):事实、争议、说理、判项、法条、金额,全部是抽取字段;判决正文(level=full / section / preview)要 cases:fulltext 授权,普通 key 403某条法条的判例
POST /v1/cases/search {"query": "…", "filters": {"law_refs": ["CN/刑法/266"]}}找美国判例
POST /v1/cases/search {"query": "qualified immunity police", "filters": {"country": "us", "court_level": "scotus"}}读一份美国判例
GET /v1/cases/read/us:577203 → id 以 us: 开头就按美国判例读(holding、争点、处理结果、引用号)细则
- 中国:刑事 265 万篇抽取完整,语料主体是 2014–2019(2020–2021 几乎为空);民事/行政/执行 1,483 万篇已补灌完(2026-10-07)。美国(country=us):只有 A 层 344 万篇,B 层长尾约 663 万未入库。每个响应带 coverage。
- query 里的案号会先精确定位。
- 中国判决的正文默认不提供:裁判文书原文里有自然人姓名、出生日期和住址,本接口只给解析后的结构化层(level=brief / detail)。level=full / section / preview 要一把带 cases:fulltext 授权的 key,没有就是 403,不扣费。
- level=brief / detail 的判项、刑期、事实、说理都是模型从判决书抽取的(sentencing 由判项正则派生);正式引用请回中国裁判文书网核对原文。
- country=us 的 id 形如 us:577203,读的时候不用再传 country;全文(level=full / section / preview)暂不可用,等判例全文库搬进 PG。
- 美国判例的 holding / 争点 / 处理结果是模型抽取的;正式引用请回 CourtListener 原文。
- 问答走 /v1/law/ask(scope=case,目前只覆盖中国判决)。
检索
POST
/v1/cases/search混合检索,每条命中一张卡片。2 credits。免费样例:
网络刷单诈骗 未遂。过滤字段
| 字段 | 类型 · op | 含义 |
|---|---|---|
| country | keyword · eqcn · us | cn(默认,中国裁判文书)/ us(美国判例)。两边字段不同:下面带 (country=us) 的只对美国生效,其余只对中国生效 |
| nature | keyword · eqcriminal · civil · all | criminal / civil / all(默认 all,仅 country=cn) |
| cause | keyword · eq any | 案由/罪名,精确匹配(见 facets crimes) |
| province | keyword · eq any | 省份 |
| judge_year | integer · range | 裁判年份区间 |
| law_refs | keyword · eq any | 引用法条枢纽键,如 CN/刑法/266 |
| verdictno | keyword · eq any | 案号精确匹配(country=cn,如 (2023)湘0902刑初105号);查案号请用这个字段,不要放进 query——PG 层只分中文词,案号里的字母数字会被忽略 |
| articles | keyword · eq any | 引用法条精确到条(country=cn,全称 + 中文条号:中华人民共和国刑法 第二百六十四条) |
| amount_max | integer · range | 判决涉及的最大金额区间(country=cn,单位元) |
| year | integer · eq range | 裁判年份区间(country=us) |
| proceeding_type | keyword · eq anycivil · criminal · administrative · bankruptcy · habeas_or_post_conviction · attorney_discipline · juvenile · other | 程序类型(country=us) |
| subject_areas | keyword · eq any | 法律领域(country=us,闭集 23 类:tort / contract / property / constitutional / employment …) |
| disposition | keyword · eq anyaffirmed · affirmed_in_part · reversed · reversed_and_remanded · vacated · vacated_and_remanded …共 12 个,/facets 可列全 | 处理结果(country=us,闭集 12 类) |
| prevailing_party | keyword · eq anyappellant_or_plaintiff · appellee_or_defendant · mixed · unclear | 胜诉方(country=us) |
| precedential_status | keyword · eq anyPublished · Unpublished · Relating-to · Separate · In-chambers · Errata · Unknown | 是否公开判例(country=us) |
| cite_count | integer · eq range | 被引次数区间(country=us) |
还有 25 个,照样能用
| 字段 | 类型 · op | 含义 |
|---|---|---|
| city | keyword · eq any | 城市 |
| court_level | keyword · eq any基层 · 中级 · 高级 · 最高 · 专门 · scotus …共 17 个,/facets 可列全 | 审级。country=cn:基层 / 中级 / 高级 / 最高 / 专门;country=us:scotus / fed_appellate / fed_district / state_supreme / state_appellate … |
| trial_round | keyword · eq any一审 · 二审 · 再审 | 一审 / 二审 / 再审 |
| decided_at | datetime · range | 裁判日期区间 |
| laws | keyword · eq any | 引用法名简称,如 刑法 |
| sentence_type | keyword · eq any有期徒刑 · 拘役 · 管制 · 无期徒刑 · 死刑 · 免予刑事处罚 · 单处罚金 | 有期徒刑 / 拘役 / 管制 / 无期徒刑 / 死刑 / 免予刑事处罚 / 单处罚金 |
| sentence_months | integer · range | 刑期(月)区间 |
| probation | bool · eq | 是否缓刑 |
| fine_amount | integer · range | 罚金(元)区间 |
| law_names | keyword · eq any | 引用法律全称(country=cn,如 中华人民共和国刑法;与 laws 的简称口径不同) |
| org_parties | keyword · eq any | 法人或其他组织当事人名(country=cn)。自然人姓名不提供筛选 |
| status | keyword · eq any生效 · 发回重审 · 终结执行 · 其他 | 文书状态(country=cn):生效 / 发回重审 / 终结执行 / 其他。只有 v2 行有值(约 204 万篇) |
| district | keyword · eq any | 区县(country=cn,没有索引,筛选较慢) |
| circumstance_tags | keyword · eq any | 量刑情节:自首 / 立功 / 累犯 / 坦白 / 认罪认罚 / 退赃退赔 / 谅解 / 从犯 / 主犯 / 未遂 / 未成年 / 前科 … |
| procedural_posture | keyword · eq anyappeal_from_final_judgment · appeal_from_conviction · interlocutory_appeal · certiorari · petition_for_review · motion_ruling …共 11 个,/facets 可列全 | 审理阶段(country=us) |
| court_id | keyword · eq any | 法院 id(country=us,CourtListener 口径,如 ca4 / scotus) |
| docket_number | keyword · eq any | 案号(country=us,精确) |
| statutes_cited | keyword · eq any | 引用的法条(country=us,原文写法) |
| issue_tags | keyword · eq any | 争点标签(country=us,模型生成的开放标签) |
| party_names | keyword · eq any | 当事人(country=us) |
| standard_of_review | keyword · eq any | 审查标准(country=us) |
| holding_by | keyword · eqatria · gemma | holding 由哪个模型给出(atria 覆盖过 gemma) |
| citation_norm | keyword · eq any | 规范化引用号(country=us,如 956 F.2d 36) |
| tier | keyword · eqa · b | 分层(country=us):a = 在向量索引里的 344 万篇;b = 只在 PG 里的长尾 |
| jurisdiction | keyword · eq anyF · FD · FS · S · SA · ST | 法域代码(country=us,CourtListener 口径:F 联邦 / FD 联邦地区 / S 州 / SA 州上诉 …) |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–1000 字符。也可以是最多 5 条的数组(批量,hits 变 results[])。 |
| top_k | integer= 10 | 1–100。 |
| fields | brief · head= brief | head 多扣 1 credit,每条附 head 视图。 |
| filters | json | 过滤 DSL 对象(见快速开始);可用字段见上表。 |
| mode | hybrid · dense · bm25= hybrid | 检索模式。不传就用第一个。 |
| offset | integer= 0 | 翻页。 |
示例
{ "domain": "cases", "query": "…", "hits": [ { "id": "8a1c3791-0cce-4094-9b28-a9a600b657c7", "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/cases/read/{uuid}三档深浅,不传就是
detail。免费样例:8a1c3791-0cce-4094-9b28-a9a600b657c7。三档
| 深浅 | credits | 返回 |
|---|---|---|
| brief | 1 | 卡片(~150 tok):案号、案由、法院、审级、日期、一句话、争议焦点、法条、量刑 |
| detail (默认) | 2 | 全部结构化字段(~500 tok):指控/争议焦点/事实/情节/说理/判项/当事人/法条/金额 |
| full 需授权 | 5 | 全文(均值 2.5k 字,p95 5.5k)。需 cases:fulltext 授权 |
侧面
同一份文档的另一个侧面,与 level 二选一。
| 侧面 | credits | 返回 |
|---|---|---|
| laws | 2 | 判决引用的法条,带可直接读的 law 链接 |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| uuid (path) 必填 | string | 文档 id(uuid)。 |
| level | brief · detail · full= detail | 读多深。 |
| extra | laws | 改读某个侧面,与 level 二选一。 |
| format | json · md · html= json | 响应形态。 |
| section | string | (level = full:只读这一节)需 cases:fulltext 授权。 |
| characters | integer= 3000 | (level = full:只读前 N 字)需 cases:fulltext 授权。 |
示例
{ "domain": "cases", "id": "8a1c3791-0cce-4094-9b28-a9a600b657c7", "level": "detail", "view": "head", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } cases:fulltext 是 key 上的一个授权,不是垂域。中国判决的正文(整篇 / 分段 / 前 N 字)。默认不开:裁判文书原文带当事人姓名、出生日期和住址,抽样 400 篇里 58% 有未脱敏真名。不需要正文的话 level=detail 已经有全部抽取字段。标了「需授权」的地方没有它就是 403,也不扣费——空 scopes 等于所有垂域,但不含任何授权。要开通去控制台的 API keys 页申请。旧写法
GET /v1/cases/doc/{id}?view=… 仍然可用。批量读
POST
/v1/cases/read最多 50 个 id,同一档。查不到的 id 返回
error: "not_found",不扣费。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| ids 必填 | string[] | 文档 id 列表。 |
| level | brief · detail · full= detail | 所有 id 共用的档。 |
| extra | laws | 改读某个侧面。 |
示例
{ "domain": "cases", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
GET
/v1/cases/facets?field={field}某个过滤字段的合法值,agent 不用猜;预聚合字段带计数,声明的枚举没有。免费、不需要 key。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| field 必填 | enum · 12 | 有 facets 的过滤字段。 |
| limit | integer= 50 | 最多返回多少个值。 |
示例
{ "domain": "cases", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } 问registered key+ /stream
POST
/v1/cases/ask判决问答:走 law 域的同一个 agent(它本来就是「先找依据条文、再看同类判决怎么判」的联合形态),默认 scope=case 只查判决;回答带 [案号] 引用,sources.cases / coverage 同 law。
effort low / medium / high 对应 50 / 100 / 200 credits。加 /stream 走 NDJSON,第一个事件一定是 billing。首个 answer_delta 之前失败会退款。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–2000 字符。问得具体;要数字就直接问数字。 |
| scope | auto · law · case · both= case | 只查判决(默认)/ 连法条一起查 |
| 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": "… [(2018)闽0181刑初1319号] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } 回答里可能出现人名。判决正文要
cases:fulltext 授权,但它读的抽取字段不需要,而当事人姓名就在抽取字段里——所以答案里可能带着自然人姓名。拿到的内容按个人信息对待。引用是真的——
answer 里的每个 id 都存在于本垂域(格式 [(2018)闽0181刑初1319号])。sources 是召回集,不是引用列表。answer_truncated 表示不完整。美国成文法
美国 53 个法域的成文法、规章与法院规则,逐条可读。
- 状态
- live
- 文档 id
law_id如uslaw:CFRANN_2024_T42_P2_S2_33- 引用格式
[42 C.F.R. § 2.33]- 更新于
- 2026-08
常用调用
找条文
POST /v1/us_law/search {"query": "disclosure of patient records without consent", "filters": {"jurisdiction": "federal", "status": "in_force"}}读一条
GET /v1/us_law/read/uslaw:CFRANN_2024_T42_P2_S2_33 → 摘要、规范类型、受约束主体、罚则、交叉引用只看州法
POST /v1/us_law/search {"query": "data breach notification", "filters": {"jurisdiction": ["ca", "ny"]}}50 州、华盛顿特区、波多黎各与《美国法典》的成文法、规章与法院规则——判例早就在了,缺的是这一侧。州法的交叉引用上游很稀疏;92.8 万条标为已废止,引用前先看 status。
细则
- 许可:CC BY 4.0 (open_us_law)(展示与再分发须按许可署名)。
- 一条 = 一个 section/条款,不是一部法。level=detail 里的 excerpt 是原文节选,不是全文。
- status=superseded 有 92.8 万条(多数是 CFR 历史年度版);引用前按 status=in_force 过滤。
- 摘要、规范类型、主题是模型生成的;引用与数额核对过原文,但正式引用请回原文。
- subjects 是开放标签(3.9 万种),适合看不适合筛。
- 检索库里没有正文:level=full 暂不可用(条文全文在 NAS open_us_law,检索库里是摘要 + 节选(excerpt))。
检索
POST
/v1/us_law/search混合检索,每条命中一张卡片。2 credits。免费样例:
HIPAA patient records disclosure。过滤字段
| 字段 | 类型 · op | 含义 |
|---|---|---|
| jurisdiction | keyword · eq any | 法域:federal 或州两字码(ca / tx / ny …,共 53 个) |
| is_federal | bool · eq | 是否联邦 |
| doc_group | keyword · eq anystatute · regulation · session_law · decision · proposed_regulation · guidance · court_rule · constitution · presidential · treaty | 文本大类 |
| kind | keyword · eq any | 细分类型(statutes / regulations / cfr_annual / ag_opinion …见 facets) |
| status | keyword · eq anyin_force · superseded · enacted · repealed · proposed · reserved …共 12 个,/facets 可列全 | 效力状态 |
| norm_types | keyword · eq anyobligation · prohibition · permission_or_authority · definition · procedure · eligibility_or_criteria …共 15 个,/facets 可列全 | 规范类型(闭集 15 类,模型判定) |
| has_penalty | bool · eq | 是否含罚则 |
还有 5 个,照样能用
| 字段 | 类型 · op | 含义 |
|---|---|---|
| penalty_types | keyword · eq anyfine · civil_penalty · imprisonment · license_sanction · forfeiture · other | 罚则类型 |
| citation | keyword · eq any | 引用号(精确,如 42 C.F.R. § 2.33) |
| subjects | keyword · eq any | 主题(模型生成的开放标签,基数很大) |
| defined_terms | keyword · eq any | 本条定义的术语 |
| regulated_parties | keyword · eq any | 受约束主体 |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–1000 字符。也可以是最多 5 条的数组(批量,hits 变 results[])。 |
| top_k | integer= 10 | 1–100。 |
| fields | brief · head= brief | head 多扣 1 credit,每条附 head 视图。 |
| filters | json | 过滤 DSL 对象(见快速开始);可用字段见上表。 |
| mode | hybrid · dense · bm25= hybrid | 检索模式。不传就用第一个。 |
| offset | integer= 0 | 翻页。 |
示例
{ "domain": "us_law", "query": "…", "hits": [ { "id": "uslaw:CFRANN_2024_T42_P2_S2_33", "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/us_law/read/{law_id}三档深浅,不传就是
detail。免费样例:uslaw:CFRANN_2024_T42_P2_S2_33。三档
| 深浅 | credits | 返回 |
|---|---|---|
| brief | 1 | 卡片:做取舍够用的字段(检索结果里那张) |
| detail (默认) | 2 | 全部结构化字段(规则字段 + 模型字段,模型字段在 _enrich.fields 里列名) |
| full | 5 | 全文(建设中:条文全文在 NAS open_us_law,检索库里是摘要 + 节选(excerpt)) |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| law_id (path) 必填 | string | 文档 id(law_id)。 |
| level | brief · detail · full= detail | 读多深。 |
| format | json · md · html= json | 响应形态。 |
示例
{ "domain": "us_law", "id": "uslaw:CFRANN_2024_T42_P2_S2_33", "level": "detail", "view": "head", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } 旧写法
GET /v1/us_law/doc/{id}?view=… 仍然可用。批量读
POST
/v1/us_law/read最多 50 个 id,同一档。查不到的 id 返回
error: "not_found",不扣费。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| ids 必填 | string[] | 文档 id 列表。 |
| level | brief · detail · full= detail | 所有 id 共用的档。 |
示例
{ "domain": "us_law", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
GET
/v1/us_law/facets?field={field}某个过滤字段的合法值,agent 不用猜;预聚合字段带计数,声明的枚举没有。免费、不需要 key。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| field 必填 | jurisdiction · doc_group · kind · status · norm_types · penalty_types | 有 facets 的过滤字段。 |
| limit | integer= 50 | 最多返回多少个值。 |
示例
{ "domain": "us_law", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } 问registered key+ /stream
POST
/v1/us_law/ask本域的 agentic 问答:模型按自描述把问题翻成检索(筛选 + 关键词),读详情后作答,引用写成 [us_law: <标题>];/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": "… [42 C.F.R. § 2.33] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } 引用是真的——
answer 里的每个 id 都存在于本垂域(格式 [42 C.F.R. § 2.33])。sources 是召回集,不是引用列表。answer_truncated 表示不完整。