法律
概览
building 26 国 33,103 部法规 / 1,537,422 条，条级混合检索，中英译文与条级抽取。
id: law_id 如 chn:law:刑法 · 引用格式 [中华人民共和国刑法 第266条]
覆盖率与偏差说明。中国民事判决目前只覆盖约 12%，且样本不随机——它跟着 enrichment 队列走。刑事判决 100%。每个 Law / Cases 响应都带 coverage 块；把它的 note 抄进 agent 的 tool description，让它对民事案例的结论加限定。引用格式：[中华人民共和国刑法 第266条] · [（2022）湘0902刑初12号]。每份判决的法律依据都归一成 CN/刑法/266 这样的 law_refs，由此有两条精确路径：law 的 cases view（法条 → 判决）和 cases 的 laws view（判决 → 法条）。
- 建设中：接口形状已定，上游上线后自动变 live。
检索即将上线
POST
/v1/law/search混合检索，返回 brief（每条约 100–300 tok）。2 credits，
fields=head 时 3。也可 GET …/search?query=&filters=<urlencoded json>。| 字段 | 类型 · op | 含义 |
|---|---|---|
| jurisdiction | keyword · eq any | ISO3：CHN / JPN / GBR / USA / DEU / KOR … |
| law_id | keyword · eq | 限定一部法 |
| law_type | keyword · eq any | 法规类型（facets） |
| domain | keyword · eq any | 法律领域（facets） |
| status | keyword · eq any in_force | repealed | not_yet | in_force / repealed / not_yet |
| norm_type | keyword · eq any | 义务 / 禁止 / 罚则 / 定义 … |
| effective_at | datetime · range | 生效日期 |
| lang | keyword · eq | 返回文本语言 zh / en，默认原文 |
参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| 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": "chn:law:刑法", "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/law/doc/{law_id}一份文档，每次一个 view。结构化 view 在
data，文本 view 在 text 并带 token_count。免费样例：chn:law:刑法。| view | credits | 返回 |
|---|---|---|
| brief | 1 | 一部法：三语标题、机关、日期、状态 + 章节树 |
| head | 2 | brief + 每章一句摘要 + 条号列表 |
| article | 3 | 一条：原文/译文/抽取/引用/被引案例数 |
| context | 3 | 一条 + 前后条 + 所属章 |
| section | 3 | 一章 (text) |
| raw | 5 | 全文 markdown (text) |
| cases | 2 | 法条 → 引用它的判决（brief 列表） |
参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| law_id (path) | string | 必填 | 文档 id（law_id）。 |
| view | brief | head | article | context | section | raw | cases | = brief | 读哪一层。 |
| article | string | 可选 | view = article | context | cases（该 view 必填） |
| lang | string | 可选 | view = article |
| window | integer | = 2 | view = context，默认 2 |
| chapter | string | 可选 | view = section（该 view 必填） |
| top_k | integer | = 10 | view = cases，默认 10 |
示例
{ "domain": "law", "id": "chn:law:刑法", "view": "section", "params": { … }, "data": { … } | "text": "…", "token_count": 1834, "truncated": false, "meta": { … } } 批量读即将上线
POST
/v1/law/docs最多 50 个 id，同一个 view。查不到的 id 返回
error: "not_found"，不扣费。参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| ids | string[] | 必填 | 文档 id 列表。 |
| view | brief | head | article | context | section | raw | cases | = brief | 所有 id 共用的 view。 |
示例
{ "domain": "law", "view": "brief", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets即将上线
GET
/v1/law/facets?field={field}某个过滤字段的合法值与计数，agent 不用猜。免费。垂域未实现时 404。
参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| field | jurisdiction | law_id | law_type | domain | status | norm_type | effective_at | lang | 必填 | 过滤字段。 |
| limit | integer | = 50 | 最多返回多少个值。 |
示例
{ "domain": "law", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } 问即将上线registered key+ /stream
POST
/v1/law/ask法条 + 判决联合 agentic 问答；响应多 sources.laws / sources.cases 和 coverage。按 effort 计 50 / 100 / 200 credits。加
/stream 走 NDJSON，第一个事件一定是 billing。首个 answer_delta 之前上游失败会退款。参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| query | string | 必填 | 1–2000 字符。问得具体；要数字就直接问数字。 |
| scope | auto | law | case | both | = auto | |
| jurisdiction | string | 可选 | ISO3，默认 auto |
| effort | default | high | xhigh | = default | 检索轮数上限，也决定价格：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, … } } } 引用是真的——
answer 里的每个 id 都存在于本垂域（格式 [中华人民共和国刑法 第266条]）。sources 是召回集，不是引用列表。answer_truncated 表示不完整。案例
building 中国裁判文书 450 万（目标 1,770 万），结构化 brief（案由/法院/审级/争议焦点/法条/金额/判项）。
id: uuid 如 … · 引用格式 [（2022）湘0902刑初12号]
- 民事判决目前只覆盖约 12% 且非随机；刑事 100%。每个响应带 coverage。
- 问答走 /v1/law/ask（scope=case）。
检索即将上线
POST
/v1/cases/search混合检索，返回 brief（每条约 100–300 tok）。2 credits，
fields=head 时 3。也可 GET …/search?query=&filters=<urlencoded json>。| 字段 | 类型 · op | 含义 |
|---|---|---|
| case_nature | keyword · eq any 刑事 | 民事 | 行政 | 执行 | 刑事 / 民事 / 行政 / 执行 |
| cause | keyword · eq any | 案由（facets） |
| province | keyword · eq any | 省份 |
| city | keyword · eq any | 城市 |
| court_level | keyword · eq any | 法院层级 |
| trial_round | keyword · eq any 一审 | 二审 | 再审 | 一审 / 二审 / 再审 |
| decided_at | datetime · range | 裁判日期 |
| law_refs | keyword · eq any | 引用法条，如 CN/刑法/266 |
| amount | integer · eq range | 涉案金额（元） |
| sentence_months | integer · eq range | 刑期（月） |
| probation | bool · eq | 是否缓刑 |
参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| 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": "…", "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/doc/{uuid}一份文档，每次一个 view。结构化 view 在
data，文本 view 在 text 并带 token_count。免费样例：…。| view | credits | 返回 |
|---|---|---|
| brief | 1 | L1 卡片 ~100 tok |
| head | 2 | 全部结构化字段 |
| section | 3 | parties / claims / facts / opinion / decision (text) |
| preview | 3 | 全文前 N 字 (text) |
| raw | 5 | 全文 (text) |
| laws | 2 | 判决 → 引用的法条（law 的 article id 列表） |
参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| uuid (path) | string | 必填 | 文档 id（uuid）。 |
| view | brief | head | section | preview | raw | laws | = brief | 读哪一层。 |
| section | string | 可选 | view = section（该 view 必填） |
| characters | integer | = 3000 | view = preview，默认 3000 |
示例
{ "domain": "cases", "id": "…", "view": "section", "params": { … }, "data": { … } | "text": "…", "token_count": 1834, "truncated": false, "meta": { … } } 批量读即将上线
POST
/v1/cases/docs最多 50 个 id，同一个 view。查不到的 id 返回
error: "not_found"，不扣费。参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| ids | string[] | 必填 | 文档 id 列表。 |
| view | brief | head | section | preview | raw | laws | = brief | 所有 id 共用的 view。 |
示例
{ "domain": "cases", "view": "brief", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets即将上线
GET
/v1/cases/facets?field={field}某个过滤字段的合法值与计数，agent 不用猜。免费。垂域未实现时 404。
参数
| 参数 | 类型 | 说明 | |
|---|---|---|---|
| field | case_nature | cause | province | city | court_level | trial_round | decided_at | law_refs | amount | sentence_months | probation | 必填 | 过滤字段。 |
| limit | integer | = 50 | 最多返回多少个值。 |
示例
{ "domain": "cases", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } }