The service currently runs on a single small machine: about 50 search requests/s and ~20 concurrent ask sessions across all users. Please keep concurrency modest (≤ 5 per client) and back off on 429 using Retry-After. Details →

Law

Overview

Statutes from two dozen-odd jurisdictions, retrieved article by article, with translations and article-level extraction.

status
live
document id
law_id e.g. 刑法
citation
[中华人民共和国刑法 第266条]

Common calls

Find statute articlesPOST /v1/law/search {"query": "刑法第266条"}
Read one articleGET /v1/law/read/<检索结果的 id>
Read a statuteGET /v1/law/read/刑法
Ask across statutes and judgmentsPOST /v1/law/ask {"query": "网络刷单诈骗未遂一般怎么判", "effort": "low"}

Coverage, and what it leaves out. Criminal judgments are complete and the civil backfill has finished, but against every court document ever published this is still a part, and what came in followed the enrichment queue rather than chance. Every Law and Cases response carries a coverage block; copy its note into your agent's tool description and the claims stay qualified.

Paging stops at 1000. On Law and Cases, offset + top_k may not pass max_window; past it the API answers 400. Narrow with filters instead of paging deeper. US opinions outside the vector tier (tier=b) answer to keywords only.

An article leads to its judgments, and back. Each judgment's legal basis is normalised into law_refs like CN/刑法/266, so extra=cases goes from an article to the judgments that applied it, and extra=laws goes from a judgment back to the articles.

The fine print
  • law_id accepts a doc_id (jpn:law:労働基準法) or a Chinese title / short title (刑法, 劳动合同法).
  • A query like '刑法第266条' (statute + article number) resolves exactly first.
  • scope=national by default: local regulations copy national text and are the main source of noise.
  • Translations and extractions are model-generated; cite text.src. needs_review=true marks translations of unusual length.
  • knowledge_fill in level=brief / detail is model-recalled metadata, not a source.

Read

GET/v1/law/read/{law_id}
Three depths. detail is the default. Free sample: 刑法.

Levels

levelcreditsreturns
brief1One statute's card: trilingual title, issuer, type, level, status, dates, one-liner, domains, article count
detail (default)2brief + summary, chapter tree (one line per chapter), key provisions, defined terms, obligations / penalties, typical questions, routing hints (~1–3k tok)
full5Full text, paged by article (offset / limit; see truncated / next_offset)

Extras

One side of the same document, in place of a level.

extracreditsreturns
cases2Article → judgments citing it: citation count + list (ranked by `query` if given, else newest first)

Parameters

ParameterTypeDescription
law_id (path) REQUIRED string Document id (law_id).
level brief · detail · full= detail How deep to read.
extra cases Read one side instead of a level.
format json · md · html= json Response shape.
offset integer= 0 (level = full)
limit integer= 200 (level = full)
section_id string 章 id,见 level=detail 的 structure (level = full: read one section)
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)

Example

{ "domain": "law", "id": "刑法", "level": "detail", "view": "head", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } }
Search hits read straight back. An id like law_id~n is one article, and the three levels narrow to it: the card, the article with its translations and extraction, then the article in context.
The older GET /v1/law/doc/{id}?view=… still works.

Read many

POST/v1/law/read
Up to 50 ids, one level. Missing ids come back with error: "not_found" and are not charged.

Parameters

ParameterTypeDescription
ids REQUIRED string[] Document ids.
level brief · detail · full= detail Level for every id.
extra cases Read one side instead.

Example

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

Facets

GET/v1/law/facets?field={field}
Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.

Parameters

ParameterTypeDescription
field REQUIRED jurisdiction · law_type · status · domain · norm_type Filter field with facets.
limit integer= 50 Max values.

Example

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

Askregistered key+ /stream

POST/v1/law/ask
Joint agentic Q&A over statutes and judgments: finds the governing articles, reads them, then checks how comparable judgments ruled; answers cite [statute art. N] / [case number], with sources.laws / sources.cases / coverage. effort low / medium / high = 50 / 100 / 200 credits. Append /stream for NDJSON; the first event is always billing. A failure before the first answer_delta is refunded.

Parameters

ParameterTypeDescription
query REQUIRED string 1–2000 characters. Be specific; ask for numbers if you want numbers.
scope auto · law · case · both= auto statutes only / judgments only / both
jurisdiction string ISO3; default unrestricted (the model decides)
effort low · medium · high= low Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it.
verbose bool= false Include the tool-call trace (tool_call / tool_result / thinking events when streaming).
top_k integer= 10 Speculative prefetch size.
stream_answer bool= true Streaming only: false emits one answer event instead of deltas.
max_rounds integer 0–8, overrides the effort preset.
force_answer_after number Seconds; hard cutover into the answer phase.
max_answer_tokens integer= 4096 Hitting it sets answer_truncated.
language string Answer language; defaults to the query’s.

Example

{ "answer": "… [中华人民共和国刑法 第266条] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } }
Answers can name people. The verbatim judgment needs the cases:fulltext permission, but the extracted fields it reads do not, and the parties are named there — so an answer may carry the name of a natural person. Treat what comes back as personal data.
Citations are real — every id in answer exists in this domain (format [中华人民共和国刑法 第266条]). sources is the retrieval set, not the citation list. answer_truncated means incomplete.

Cases

Chinese judgments: criminal is complete, and the civil backfill has finished too. Against every court document ever published this is still a part, and every response says so in coverage.

status
live
document id
uuid e.g. 8a1c3791-0cce-4094-9b28-a9a600b657c7
citation
[(2018)闽0181刑初1319号]

Common calls

Find judgmentsPOST /v1/cases/search {"query": "网络刷单诈骗 未遂", "filters": {"province": "浙江省", "judge_year": {"gte": 2018}}}
Read a judgmentGET /v1/cases/read/<uuid>
Judgments citing an articlePOST /v1/cases/search {"query": "…", "filters": {"law_refs": ["CN/刑法/266"]}}
Find US opinionsPOST /v1/cases/search {"query": "qualified immunity police", "filters": {"country": "us", "court_level": "scotus"}}
Read a US opinionGET /v1/cases/read/us:577203
The fine print
  • China: 2.65M criminal judgments fully extracted, mostly 2014–2019 (2020–2021 nearly empty); 14.83M civil / administrative / enforcement judgments finished ingesting on 2026-10-07. US (country=us): tier A only (3.44M); the ~6.63M tier-B long tail is not indexed. Every response carries coverage.
  • A case number in the query resolves exactly first.
  • Chinese judgment text is not served by default: the original documents carry party names, dates of birth and home addresses, so this API exposes only the parsed layer (level=brief / detail). level=full / section / preview need an API key carrying the cases:fulltext grant — without it the call is a 403 and costs nothing.
  • At level=brief / detail the verdict, sentence, facts and reasoning are all model extractions (sentencing is derived from the verdict by regex); cite the official Chinese judgment site for anything formal.
  • country=us ids look like us:577203 — reading one needs no country parameter; full text (level=full / section / preview) is not available yet, pending the move of the opinion store into PG.
  • US holdings, issues and dispositions are model-extracted; cite CourtListener for anything formal.
  • Ask goes through /v1/law/ask (scope=case, Chinese judgments only for now).

Read

GET/v1/cases/read/{uuid}
Three depths. detail is the default. Free sample: 8a1c3791-0cce-4094-9b28-a9a600b657c7.

Levels

levelcreditsreturns
brief1Card (~150 tok): case number, cause, court, level, date, one-line summary, disputed issues, cited articles, sentencing
detail (default)2Every structured field (~500 tok): claims, disputed issues, facts, circumstances, reasoning, outcome, parties, articles, amounts
full permission5Full text (mean 2.5k chars, p95 5.5k). Needs the cases:fulltext grant

Extras

One side of the same document, in place of a level.

extracreditsreturns
laws2Articles the judgment cites, with readable law links

Parameters

ParameterTypeDescription
uuid (path) REQUIRED string Document id (uuid).
level brief · detail · full= detail How deep to read.
extra laws Read one side instead of a level.
format json · md · html= json Response shape.
section string (level = full: read one section) Needs the cases:fulltext permission.
characters integer= 3000 (level = full: first N characters) Needs the cases:fulltext permission.

Example

{ "domain": "cases", "id": "8a1c3791-0cce-4094-9b28-a9a600b657c7", "level": "detail", "view": "head", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } }
cases:fulltext is a permission on the key, not a domain. Verbatim text of Chinese judgments (whole, by section, or first N characters). Off by default: the originals carry party names, dates of birth and home addresses (58% of a 400-judgment sample had an unmasked name). level=detail already has every extracted field. Everything marked permission is a 403 without it and costs nothing — an empty scope list means every domain, never a permission. Ask for it on the API keys page in the console.
The older GET /v1/cases/doc/{id}?view=… still works.

Read many

POST/v1/cases/read
Up to 50 ids, one level. Missing ids come back with error: "not_found" and are not charged.

Parameters

ParameterTypeDescription
ids REQUIRED string[] Document ids.
level brief · detail · full= detail Level for every id.
extra laws Read one side instead.

Example

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

Facets

GET/v1/cases/facets?field={field}
Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.

Parameters

ParameterTypeDescription
field REQUIRED enum · 12 Filter field with facets.
limit integer= 50 Max values.

Example

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

Askregistered key+ /stream

POST/v1/cases/ask
Q&A over judgments: served by the same agent as the law domain (which already combines 'find the governing articles, then see how comparable judgments ruled'); scope defaults to case, i.e. judgments only. Answers cite [case number], with sources.cases / coverage as in law. effort low / medium / high = 50 / 100 / 200 credits. Append /stream for NDJSON; the first event is always billing. A failure before the first answer_delta is refunded.

Parameters

ParameterTypeDescription
query REQUIRED string 1–2000 characters. Be specific; ask for numbers if you want numbers.
scope auto · law · case · both= case judgments only (default) / statutes too
effort low · medium · high= low Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it.
verbose bool= false Include the tool-call trace (tool_call / tool_result / thinking events when streaming).
top_k integer= 10 Speculative prefetch size.
stream_answer bool= true Streaming only: false emits one answer event instead of deltas.
max_rounds integer 0–8, overrides the effort preset.
force_answer_after number Seconds; hard cutover into the answer phase.
max_answer_tokens integer= 4096 Hitting it sets answer_truncated.
language string Answer language; defaults to the query’s.

Example

{ "answer": "… [(2018)闽0181刑初1319号] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } }
Answers can name people. The verbatim judgment needs the cases:fulltext permission, but the extracted fields it reads do not, and the parties are named there — so an answer may carry the name of a natural person. Treat what comes back as personal data.
Citations are real — every id in answer exists in this domain (format [(2018)闽0181刑初1319号]). sources is the retrieval set, not the citation list. answer_truncated means incomplete.

US law

Federal and state statutes, regulations and court rules, clause by clause, across 53 US jurisdictions.

status
live
document id
law_id e.g. uslaw:CFRANN_2024_T42_P2_S2_33
citation
[42 C.F.R. § 2.33]
updated
2026-08

Common calls

Find provisionsPOST /v1/us_law/search {"query": "disclosure of patient records without consent", "filters": {"jurisdiction": "federal", "status": "in_force"}}
Read one provisionGET /v1/us_law/read/uslaw:CFRANN_2024_T42_P2_S2_33
One state onlyPOST /v1/us_law/search {"query": "data breach notification", "filters": {"jurisdiction": ["ca", "ny"]}}

Statutes, regulations and court rules for all 50 states, DC, Puerto Rico and the US Code — the side that was missing while the judgments were already here. Cross-references are thin upstream on state law; 928k provisions are marked superseded, so check status before quoting one.

The fine print
  • Licence: CC BY 4.0 (open_us_law) — attribution required when displaying or redistributing.
  • One document = one section / provision, not a whole act. The `excerpt` in level=detail is a snippet, not the full text.
  • 928k provisions are status=superseded (mostly historical CFR annual editions) — filter status=in_force before citing.
  • Summaries, norm types and subjects are model-generated; citations and figures were checked against the text, but cite the source for anything formal.
  • `subjects` is an open label set (39k values): good to read, poor to filter on.
  • The index holds no full text: level=full is not available yet (the provision text lives on NAS (open_us_law); the index carries the summary plus an excerpt).

Read

GET/v1/us_law/read/{law_id}
Three depths. detail is the default. Free sample: uslaw:CFRANN_2024_T42_P2_S2_33.

Levels

levelcreditsreturns
brief1Card: the fields needed to triage, same as in search hits
detail (default)2Every structured field (rule-derived plus model-generated; model fields are listed in _enrich.fields)
full5Full text (not available yet: the provision text lives on NAS (open_us_law); the index carries the summary plus an excerpt)

Parameters

ParameterTypeDescription
law_id (path) REQUIRED string Document id (law_id).
level brief · detail · full= detail How deep to read.
format json · md · html= json Response shape.

Example

{ "domain": "us_law", "id": "uslaw:CFRANN_2024_T42_P2_S2_33", "level": "detail", "view": "head", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } }
The older GET /v1/us_law/doc/{id}?view=… still works.

Read many

POST/v1/us_law/read
Up to 50 ids, one level. Missing ids come back with error: "not_found" and are not charged.

Parameters

ParameterTypeDescription
ids REQUIRED string[] Document ids.
level brief · detail · full= detail Level for every id.

Example

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

Facets

GET/v1/us_law/facets?field={field}
Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.

Parameters

ParameterTypeDescription
field REQUIRED jurisdiction · doc_group · kind · status · norm_types · penalty_types Filter field with facets.
limit integer= 50 Max values.

Example

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

Askregistered key+ /stream

POST/v1/us_law/ask
Agentic Q&A over this domain: the model turns the question into filters plus keywords from the domain's own self-description, reads the hits and answers with [us_law: ] citations; /stream is NDJSON with real token deltas. <code>effort</code> low / medium / high = 50 / 100 / 200 credits. Append <code>/stream</code> for NDJSON; the first event is always <code>billing</code>. A failure before the first <code>answer_delta</code> is refunded.</div> <h4>Parameters</h4> <div class="tblwrap"><table class="tbl t3 tparam"> <thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead> <tbody> <tr> <td>query<span class="req"> REQUIRED</span></td> <td class="ty">string</td> <td>1–2000 characters. Be specific; ask for numbers if you want numbers.</td> </tr><tr> <td>effort</td> <td class="ty">low · medium · high<span class="def">= low</span></td> <td>Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it.</td> </tr><tr> <td>verbose</td> <td class="ty">bool<span class="def">= false</span></td> <td>Include the tool-call trace (tool_call / tool_result / thinking events when streaming).</td> </tr><tr> <td>top_k</td> <td class="ty">integer<span class="def">= 10</span></td> <td>Speculative prefetch size.</td> </tr><tr> <td>stream_answer</td> <td class="ty">bool<span class="def">= true</span></td> <td>Streaming only: false emits one answer event instead of deltas.</td> </tr><tr> <td>max_rounds</td> <td class="ty">integer</td> <td>0–8, overrides the effort preset.</td> </tr><tr> <td>force_answer_after</td> <td class="ty">number</td> <td>Seconds; hard cutover into the answer phase.</td> </tr><tr> <td>max_answer_tokens</td> <td class="ty">integer<span class="def">= 4096</span></td> <td>Hitting it sets answer_truncated.</td> </tr><tr> <td>language</td> <td class="ty">string</td> <td>Answer language; defaults to the query’s.</td> </tr> </tbody> </table></div> <h4>Example</h4> <pre class="code">{ "answer": "… [42 C.F.R. § 2.33] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } }</pre> <div class="callout "><b>Citations are real</b> — every id in <code>answer</code> exists in this domain (format <code>[42 C.F.R. § 2.33]</code>). <b><code>sources</code> is the retrieval set</b>, not the citation list. <b><code>answer_truncated</code> means incomplete.</b></div> </section> </div> </div> <aside class="pg" data-playground> <div class="pg-handle" data-pg-handle></div> <div class="pg-head"><b>Playground</b><span class="hint">Follows the section you are reading</span><button class="icon-btn" data-pg-close type="button" aria-label="Close">✕</button></div> <div class="pg-body" data-pg-body></div> <script type="application/json" data-pg-specs>[{"id":"law-search","domain":"law","method":"POST","path":"/v1/law/search","auth":"optional","status":"live","title":{"en":"Search","zh":"检索"},"summary":{"en":"Hybrid retrieval, one card per hit. 2 credits. Free sample: <code>诈骗罪 量刑</code>.<h4 class=\"sub\">Filter fields</h4><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>field</th><th>type · ops</th><th>meaning</th></tr></thead><tbody><tr><td class=\"mono\">jurisdiction</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">CHN · JPN · GBR · USA · DEU · KOR <span class=\"dim\">… 26 values, /facets lists them all</span></span></td><td>ISO3 jurisdiction, e.g. CHN / JPN / GBR / USA / DEU / KOR; several allowed</td></tr><tr><td class=\"mono\">law_id</td><td class=\"mono dim\">keyword · eq</td><td>Restrict to one statute: doc_id or Chinese title / short title</td></tr><tr><td class=\"mono\">status</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">in_force · repealed · not_yet · unknown</span></td><td>in_force / repealed / not_yet / unknown</td></tr></tbody></table></div><details class=\"adv\"><summary>6 more, all usable</summary><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>field</th><th>type · ops</th><th>meaning</th></tr></thead><tbody><tr><td class=\"mono\">scope</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">national · all · local</span></td><td>national (default, no local regulations) / all / local</td></tr><tr><td class=\"mono\">granularity</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">article · law</span></td><td>article (default, article-level hits) / law (which statute to look at)</td></tr><tr><td class=\"mono\">law_type</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">act · code · regulation · ordinance · decree · judicial_interpretation · constitution · other</span></td><td>Instrument type</td></tr><tr><td class=\"mono\">domain</td><td class=\"mono dim\">keyword · eq any</td><td>Legal domain (domain_global id, see facets)</td></tr><tr><td class=\"mono\">norm_type</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">procedure · obligation · scope · permission · prohibition · penalty · definition · right · principle</span></td><td>Norm type: obligation / prohibition / penalty / permission / procedure / definition / scope … (see facets)</td></tr><tr><td class=\"mono\">effective_at</td><td class=\"mono dim\">datetime · range</td><td>Effective date range</td></tr></tbody></table></div></details>","zh":"混合检索,每条命中一张卡片。2 credits。免费样例:<code>诈骗罪 量刑</code>。<h4 class=\"sub\">过滤字段</h4><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>字段</th><th>类型 · op</th><th>含义</th></tr></thead><tbody><tr><td class=\"mono\">jurisdiction</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">CHN · JPN · GBR · USA · DEU · KOR <span class=\"dim\">…共 26 个,/facets 可列全</span></span></td><td>ISO3,如 CHN / JPN / GBR / USA / DEU / KOR;可多选</td></tr><tr><td class=\"mono\">law_id</td><td class=\"mono dim\">keyword · eq</td><td>限定一部法:doc_id 或中文法名/简称</td></tr><tr><td class=\"mono\">status</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">in_force · repealed · not_yet · unknown</span></td><td>in_force / repealed / not_yet / unknown</td></tr></tbody></table></div><details class=\"adv\"><summary>还有 6 个,照样能用</summary><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>字段</th><th>类型 · op</th><th>含义</th></tr></thead><tbody><tr><td class=\"mono\">scope</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">national · all · local</span></td><td>national(默认,不含地方法规)/ all / local</td></tr><tr><td class=\"mono\">granularity</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">article · law</span></td><td>article(默认,条级命中)/ law(部级:这个问题该查哪部法)</td></tr><tr><td class=\"mono\">law_type</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">act · code · regulation · ordinance · decree · judicial_interpretation · constitution · other</span></td><td>法规类型</td></tr><tr><td class=\"mono\">domain</td><td class=\"mono dim\">keyword · eq any</td><td>法律领域(domain_global id,见 facets)</td></tr><tr><td class=\"mono\">norm_type</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">procedure · obligation · scope · permission · prohibition · penalty · definition · right · principle</span></td><td>规范类型:obligation / prohibition / penalty / permission / procedure / definition / scope …(见 facets)</td></tr><tr><td class=\"mono\">effective_at</td><td class=\"mono dim\">datetime · range</td><td>生效日期区间</td></tr></tbody></table></div></details>"},"params":[{"name":"query","type":"string","required":true,"in":"body","example":"诈骗罪 量刑","desc":{"en":"1–1000 characters. Or an array of up to 5 (batch; hits become results[]).","zh":"1–1000 字符。也可以是最多 5 条的数组(批量,hits 变 results[])。"}},{"name":"top_k","type":"integer","default":"10","in":"body","desc":{"en":"1–100.","zh":"1–100。"}},{"name":"fields","type":"enum","options":["brief","head"],"default":"brief","in":"body","desc":{"en":"head costs one more credit and returns the head view per hit.","zh":"head 多扣 1 credit,每条附 head 视图。"}},{"name":"filters","type":"json","in":"body","example":"","desc":{"en":"Filter DSL object (see Getting started); declared fields are listed above.","zh":"过滤 DSL 对象(见快速开始);可用字段见上表。"}},{"name":"mode","type":"enum","options":["hybrid","dense","bm25"],"default":"hybrid","in":"body","advanced":false,"desc":{"en":"Retrieval mode. Leave it out to use the first.","zh":"检索模式。不传就用第一个。"}},{"name":"offset","type":"integer","default":"0","in":"body","advanced":true,"desc":{"en":"Pagination.","zh":"翻页。"}}],"example":"{ \"domain\": \"law\", \"query\": \"…\", \"hits\": [ { \"id\": \"刑法\", \"score\": 0.83, \"brief\": { … } } ], \"total\": null, \"coverage\": …, \"warnings\": [],\n \"meta\": { \"request_id\": \"req_…\", \"credits\": { \"charged\": 2, \"balance\": 1998, \"pool\": \"allowance\" }, \"latency_ms\": 41, \"cached\": false } }","notes":[{"html":{"en":"<b>Undeclared filter fields return 400</b> rather than being ignored silently. Filters combine with AND; <code>_or</code> / <code>_not</code> are available.","zh":"<b>用了未声明的过滤字段返回 400</b>,不会静默忽略。过滤条件是 AND;可用 <code>_or</code> / <code>_not</code>。"}},{"html":{"en":"<b>A hit id reads straight back</b>: an article hit comes back as <code><law_id>~<n></code> (e.g. <code>chn:law:中华人民共和国刑法~296</code>), so <code>GET /v1/law/doc/<hit.id></code> returns that article — no need to take the law apart and pass <code>article</code> yourself. (It used to be <code>#</code>, which a URL treats as a fragment and truncates.)","zh":"<b>检索结果的 id 可以直接拿去读</b>:条文命中的 id 形如 <code><law_id>~<n></code>(如 <code>chn:law:中华人民共和国刑法~296</code>),<code>GET /v1/law/doc/<hit.id></code> 读到的就是这一条,不用自己拆出法名再传 <code>article</code>。(原来用 <code>#</code>,在 URL 里是锚点会被截掉。)"}}]},{"id":"law-read","domain":"law","method":"GET","path":"/v1/law/read/{law_id}","auth":"optional","status":"live","title":{"en":"Read","zh":"读"},"summary":{"en":"Three depths. <code>detail</code> is the default. Free sample: <code>刑法</code>.<h4 class=\"sub\">Levels</h4><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>level</th><th>credits</th><th>returns</th></tr></thead><tbody><tr><td class=\"mono\">brief</td><td class=\"mono num\">1</td><td>One statute's card: trilingual title, issuer, type, level, status, dates, one-liner, domains, article count</td></tr><tr><td class=\"mono\">detail <span class=\"dim\">(default)</span></td><td class=\"mono num\">2</td><td>brief + summary, chapter tree (one line per chapter), key provisions, defined terms, obligations / penalties, typical questions, routing hints (~1–3k tok)</td></tr><tr><td class=\"mono\">full</td><td class=\"mono num\">5</td><td>Full text, paged by article (offset / limit; see truncated / next_offset)</td></tr></tbody></table></div><h4 class=\"sub\">Extras</h4><p>One side of the same document, in place of a level.</p><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>extra</th><th>credits</th><th>returns</th></tr></thead><tbody><tr><td class=\"mono\">cases</td><td class=\"mono num\">2</td><td>Article → judgments citing it: citation count + list (ranked by `query` if given, else newest first)</td></tr></tbody></table></div>","zh":"三档深浅,不传就是 <code>detail</code>。免费样例:<code>刑法</code>。<h4 class=\"sub\">三档</h4><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>深浅</th><th>credits</th><th>返回</th></tr></thead><tbody><tr><td class=\"mono\">brief</td><td class=\"mono num\">1</td><td>一部法的卡片:三语标题、机关、类型、层级、状态、日期、一句话、领域、条数</td></tr><tr><td class=\"mono\">detail <span class=\"dim\">(默认)</span></td><td class=\"mono num\">2</td><td>brief + 摘要、章节树(每章一句)、关键条款、术语表、义务/罚则、典型问题、路由提示(~1–3k tok)</td></tr><tr><td class=\"mono\">full</td><td class=\"mono num\">5</td><td>全文,按条分页(offset / limit;看 truncated / next_offset)</td></tr></tbody></table></div><h4 class=\"sub\">侧面</h4><p>同一份文档的另一个侧面,与 level 二选一。</p><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>侧面</th><th>credits</th><th>返回</th></tr></thead><tbody><tr><td class=\"mono\">cases</td><td class=\"mono num\">2</td><td>法条 → 引用它的判决:引用计数 + 列表(给 query 按相关性排,否则按年份倒序)</td></tr></tbody></table></div>"},"params":[{"name":"law_id","type":"string","required":true,"in":"path","example":"刑法","desc":{"en":"Document id (law_id).","zh":"文档 id(law_id)。"}},{"name":"level","type":"enum","options":["brief","detail","full"],"default":"detail","desc":{"en":"How deep to read.","zh":"读多深。"}},{"name":"extra","type":"enum","options":["","cases"],"desc":{"en":"Read one side instead of a level.","zh":"改读某个侧面,与 level 二选一。"}},{"name":"format","type":"enum","options":["json","md","html"],"default":"json","desc":{"en":"Response shape.","zh":"响应形态。"}},{"name":"offset","type":"integer","default":"0","required":false,"desc":{"en":" (level = full)","zh":" (level = full)"},"when":{"param":"level","values":["full"]}},{"name":"limit","type":"integer","default":"200","required":false,"desc":{"en":" (level = full)","zh":" (level = full)"},"when":{"param":"level","values":["full"]}},{"name":"section_id","type":"string","required":false,"desc":{"en":"章 id,见 level=detail 的 structure (level = full: read one section)","zh":"章 id,见 level=detail 的 structure (level = full:只读这一节)"},"when":{"param":"level","values":["full"]}},{"name":"article","type":"string","required":false,"desc":{"en":"id 是检索结果的 law_id~n 时不用给 (extra = cases)","zh":"id 是检索结果的 law_id~n 时不用给 (extra = cases)"},"when":{"param":"extra","values":["cases"]},"example":"266"},{"name":"query","type":"string","required":false,"desc":{"en":" (extra = cases)","zh":" (extra = cases)"},"when":{"param":"extra","values":["cases"]}},{"name":"nature","type":"string","default":"all","required":false,"desc":{"en":"criminal | civil | all (extra = cases)","zh":"criminal | civil | all (extra = cases)"},"when":{"param":"extra","values":["cases"]}},{"name":"top_k","type":"integer","default":"10","required":false,"desc":{"en":" (extra = cases)","zh":" (extra = cases)"},"when":{"param":"extra","values":["cases"]}}],"example":"{ \"domain\": \"law\", \"id\": \"刑法\", \"level\": \"detail\", \"view\": \"head\", \"data\": { … } | \"text\": \"…\", \"token_count\": 1834, \"meta\": { … } }","notes":[{"html":{"en":"<b>Search hits read straight back.</b> An id like <code>law_id~n</code> is one article, and the three levels narrow to it: the card, the article with its translations and extraction, then the article in context.","zh":"<b>检索结果可以直接读。</b><code>law_id~n</code> 这样的 id 就是一条法条,三档也跟着收窄:卡片、这一条(原文 + 译文 + 抽取)、连同上下文。"}},{"html":{"en":"The older <code>GET /v1/law/doc/{id}?view=…</code> still works.","zh":"旧写法 <code>GET /v1/law/doc/{id}?view=…</code> 仍然可用。"}}]},{"id":"law-read-batch","domain":"law","method":"POST","path":"/v1/law/read","auth":"token","status":"live","title":{"en":"Read many","zh":"批量读"},"summary":{"en":"Up to 50 ids, one level. Missing ids come back with <code>error: \"not_found\"</code> and are not charged.","zh":"最多 50 个 id,同一档。查不到的 id 返回 <code>error: \"not_found\"</code>,不扣费。"},"params":[{"name":"ids","type":"array","list":true,"required":true,"in":"body","example":"刑法","desc":{"en":"Document ids.","zh":"文档 id 列表。"}},{"name":"level","type":"enum","options":["brief","detail","full"],"default":"detail","in":"body","desc":{"en":"Level for every id.","zh":"所有 id 共用的档。"}},{"name":"extra","type":"enum","options":["","cases"],"in":"body","desc":{"en":"Read one side instead.","zh":"改读某个侧面。"}}],"example":"{ \"domain\": \"law\", \"level\": \"detail\", \"docs\": [ { \"id\": \"…\", \"data\": { … } }, { \"id\": \"…\", \"error\": \"not_found\" } ], \"meta\": { … } }"},{"id":"law-facets","domain":"law","method":"GET","path":"/v1/law/facets","auth":"none","status":"live","title":{"en":"Facets","zh":"Facets"},"summary":{"en":"Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.","zh":"某个过滤字段的合法值,agent 不用猜;预聚合字段带计数,声明的枚举没有。免费、不需要 key。"},"params":[{"name":"field","type":"enum","options":["jurisdiction","law_type","status","domain","norm_type"],"required":true,"example":"jurisdiction","desc":{"en":"Filter field with facets.","zh":"有 facets 的过滤字段。"}},{"name":"limit","type":"integer","default":"50","advanced":true,"desc":{"en":"Max values.","zh":"最多返回多少个值。"}}],"example":"{ \"domain\": \"law\", \"field\": \"…\", \"values\": [ { \"value\": \"…\", \"count\": 3120 } ], \"meta\": { … } }"},{"id":"law-ask","domain":"law","method":"POST","path":"/v1/law/ask","auth":"registered","status":"live","stream":true,"agentic":true,"title":{"en":"Ask","zh":"问"},"summary":{"en":"Joint agentic Q&A over statutes and judgments: finds the governing articles, reads them, then checks how comparable judgments ruled; answers cite [statute art. N] / [case number], with sources.laws / sources.cases / coverage. <code>effort</code> low / medium / high = 50 / 100 / 200 credits. Append <code>/stream</code> for NDJSON; the first event is always <code>billing</code>. A failure before the first <code>answer_delta</code> is refunded.","zh":"法条 + 判决联合 agentic 问答:先找依据条文、读原文,再看同类判决怎么判;回答带 [法名 第N条] / [案号] 引用,多 sources.laws / sources.cases / coverage。<code>effort</code> low / medium / high 对应 50 / 100 / 200 credits。加 <code>/stream</code> 走 NDJSON,第一个事件一定是 <code>billing</code>。首个 <code>answer_delta</code> 之前失败会退款。"},"params":[{"name":"query","type":"string","required":true,"in":"body","example":"网络刷单诈骗三万元,未遂,量刑区间是多少","desc":{"en":"1–2000 characters. Be specific; ask for numbers if you want numbers.","zh":"1–2000 字符。问得具体;要数字就直接问数字。"}},{"name":"scope","type":"enum","options":["auto","law","case","both"],"default":"auto","required":false,"desc":{"en":"statutes only / judgments only / both","zh":"只查法条 / 只查判决 / 都查"},"in":"body"},{"name":"jurisdiction","type":"string","required":false,"desc":{"en":"ISO3; default unrestricted (the model decides)","zh":"ISO3,默认不限(模型按问题判断)"},"in":"body","example":"CHN"},{"name":"effort","type":"enum","options":["low","medium","high"],"default":"low","in":"body","desc":{"en":"Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it.","zh":"检索轮数,也决定价格:50 / 100 / 200 credits。套餐限制最高档。"}},{"name":"verbose","type":"bool","default":"false","in":"body","desc":{"en":"Include the tool-call trace (tool_call / tool_result / thinking events when streaming).","zh":"返回工具调用轨迹(流式时多 tool_call / tool_result / thinking 事件)。"}},{"name":"top_k","type":"integer","default":"10","in":"body","advanced":true,"desc":{"en":"Speculative prefetch size.","zh":"预取候选数。"}},{"name":"stream_answer","type":"bool","default":"true","in":"body","advanced":true,"desc":{"en":"Streaming only: false emits one answer event instead of deltas.","zh":"仅流式:false 时只发一个 answer 事件。"}},{"name":"max_rounds","type":"integer","in":"body","advanced":true,"desc":{"en":"0–8, overrides the effort preset.","zh":"0–8,覆盖 effort 预设。"}},{"name":"force_answer_after","type":"number","in":"body","advanced":true,"desc":{"en":"Seconds; hard cutover into the answer phase.","zh":"秒;强制切入作答阶段。"}},{"name":"max_answer_tokens","type":"integer","default":"4096","in":"body","advanced":true,"desc":{"en":"Hitting it sets answer_truncated.","zh":"触顶时置 answer_truncated。"}},{"name":"language","type":"string","in":"body","advanced":true,"desc":{"en":"Answer language; defaults to the query’s.","zh":"回答语言,默认跟随 query。"}}],"example":"{ \"answer\": \"… [中华人民共和国刑法 第266条] …\", \"sources\": [ … ], \"stats\": { \"rounds\": 1, \"elapsed_s\": 6.2, \"answer_truncated\": false }, \"coverage\"?: { … }, \"meta\": { \"credits\": { \"charged\": 50, … } } }","notes":[{"html":{"en":"<b>Answers can name people.</b> The verbatim judgment needs the <code>cases:fulltext</code> permission, but the extracted fields it reads do not, and the parties are named there — so an answer may carry the name of a natural person. Treat what comes back as personal data.","zh":"<b>回答里可能出现人名。</b>判决正文要 <code>cases:fulltext</code> 授权,但它读的抽取字段不需要,而当事人姓名就在抽取字段里——所以答案里可能带着自然人姓名。拿到的内容按个人信息对待。"}},{"html":{"en":"<b>Citations are real</b> — every id in <code>answer</code> exists in this domain (format <code>[中华人民共和国刑法 第266条]</code>). <b><code>sources</code> is the retrieval set</b>, not the citation list. <b><code>answer_truncated</code> means incomplete.</b>","zh":"<b>引用是真的</b>——<code>answer</code> 里的每个 id 都存在于本垂域(格式 <code>[中华人民共和国刑法 第266条]</code>)。<b><code>sources</code> 是召回集</b>,不是引用列表。<b><code>answer_truncated</code> 表示不完整。</b>"}}]},{"id":"cases-search","domain":"cases","method":"POST","path":"/v1/cases/search","auth":"optional","status":"live","title":{"en":"Search","zh":"检索"},"summary":{"en":"Hybrid retrieval, one card per hit. 2 credits. Free sample: <code>网络刷单诈骗 未遂</code>.<h4 class=\"sub\">Filter fields</h4><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>field</th><th>type · ops</th><th>meaning</th></tr></thead><tbody><tr><td class=\"mono\">country</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">cn · us</span></td><td>cn (default, Chinese judgments) / us (US opinions). The two have different fields: filters marked (country=us) apply to US only, the rest to China only</td></tr><tr><td class=\"mono\">nature</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">criminal · civil · all</span></td><td>criminal / civil / all (default all; country=cn only)</td></tr><tr><td class=\"mono\">cause</td><td class=\"mono dim\">keyword · eq any</td><td>Cause of action / crime, exact match (see facets)</td></tr><tr><td class=\"mono\">province</td><td class=\"mono dim\">keyword · eq any</td><td>Province</td></tr><tr><td class=\"mono\">judge_year</td><td class=\"mono dim\">integer · range</td><td>Decision year range</td></tr><tr><td class=\"mono\">law_refs</td><td class=\"mono dim\">keyword · eq any</td><td>Cited article key, e.g. CN/刑法/266</td></tr><tr><td class=\"mono\">verdictno</td><td class=\"mono dim\">keyword · eq any</td><td>Exact case number (country=cn). Use this filter rather than the query text: the Postgres layer tokenises Chinese only</td></tr><tr><td class=\"mono\">articles</td><td class=\"mono dim\">keyword · eq any</td><td>Cited provision, to the article (country=cn; full law name + Chinese article number)</td></tr><tr><td class=\"mono\">amount_max</td><td class=\"mono dim\">integer · range</td><td>Largest amount in the judgment, range (country=cn, CNY)</td></tr><tr><td class=\"mono\">year</td><td class=\"mono dim\">integer · eq range</td><td>Decision year, range (country=us)</td></tr><tr><td class=\"mono\">proceeding_type</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">civil · criminal · administrative · bankruptcy · habeas_or_post_conviction · attorney_discipline · juvenile · other</span></td><td>Proceeding type (country=us)</td></tr><tr><td class=\"mono\">subject_areas</td><td class=\"mono dim\">keyword · eq any</td><td>Subject area (country=us, closed set of 23)</td></tr><tr><td class=\"mono\">disposition</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">affirmed · affirmed_in_part · reversed · reversed_and_remanded · vacated · vacated_and_remanded <span class=\"dim\">… 12 values, /facets lists them all</span></span></td><td>Disposition (country=us, closed set of 12)</td></tr><tr><td class=\"mono\">prevailing_party</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">appellant_or_plaintiff · appellee_or_defendant · mixed · unclear</span></td><td>Prevailing party (country=us)</td></tr><tr><td class=\"mono\">precedential_status</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">Published · Unpublished · Relating-to · Separate · In-chambers · Errata · Unknown</span></td><td>Precedential status (country=us)</td></tr><tr><td class=\"mono\">cite_count</td><td class=\"mono dim\">integer · eq range</td><td>Citation count, range (country=us)</td></tr></tbody></table></div><details class=\"adv\"><summary>25 more, all usable</summary><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>field</th><th>type · ops</th><th>meaning</th></tr></thead><tbody><tr><td class=\"mono\">city</td><td class=\"mono dim\">keyword · eq any</td><td>City</td></tr><tr><td class=\"mono\">court_level</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">基层 · 中级 · 高级 · 最高 · 专门 · scotus <span class=\"dim\">… 17 values, /facets lists them all</span></span></td><td>Court level. country=cn: 基层 / 中级 / 高级 / 最高 / 专门; country=us: scotus / fed_appellate / fed_district / state_supreme / state_appellate …</td></tr><tr><td class=\"mono\">trial_round</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">一审 · 二审 · 再审</span></td><td>Trial round</td></tr><tr><td class=\"mono\">decided_at</td><td class=\"mono dim\">datetime · range</td><td>Decision date range</td></tr><tr><td class=\"mono\">laws</td><td class=\"mono dim\">keyword · eq any</td><td>Cited statute short title, e.g. 刑法</td></tr><tr><td class=\"mono\">sentence_type</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">有期徒刑 · 拘役 · 管制 · 无期徒刑 · 死刑 · 免予刑事处罚 · 单处罚金</span></td><td>Sentence type</td></tr><tr><td class=\"mono\">sentence_months</td><td class=\"mono dim\">integer · range</td><td>Sentence length in months, range</td></tr><tr><td class=\"mono\">probation</td><td class=\"mono dim\">bool · eq</td><td>Probation granted</td></tr><tr><td class=\"mono\">fine_amount</td><td class=\"mono dim\">integer · range</td><td>Fine amount (CNY), range</td></tr><tr><td class=\"mono\">law_names</td><td class=\"mono dim\">keyword · eq any</td><td>Cited law, full name (country=cn; laws uses short names)</td></tr><tr><td class=\"mono\">org_parties</td><td class=\"mono dim\">keyword · eq any</td><td>Organisation party name (country=cn). Natural persons are not filterable</td></tr><tr><td class=\"mono\">status</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">生效 · 发回重审 · 终结执行 · 其他</span></td><td>Document status (country=cn); only the ~2.04M v2 rows have it</td></tr><tr><td class=\"mono\">district</td><td class=\"mono dim\">keyword · eq any</td><td>District (country=cn; not indexed, slower)</td></tr><tr><td class=\"mono\">circumstance_tags</td><td class=\"mono dim\">keyword · eq any</td><td>Sentencing circumstances: 自首 / 立功 / 累犯 / 认罪认罚 / 退赃退赔 / 未遂 …</td></tr><tr><td class=\"mono\">procedural_posture</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">appeal_from_final_judgment · appeal_from_conviction · interlocutory_appeal · certiorari · petition_for_review · motion_ruling <span class=\"dim\">… 11 values, /facets lists them all</span></span></td><td>Procedural posture (country=us)</td></tr><tr><td class=\"mono\">court_id</td><td class=\"mono dim\">keyword · eq any</td><td>Court id (country=us, CourtListener)</td></tr><tr><td class=\"mono\">docket_number</td><td class=\"mono dim\">keyword · eq any</td><td>Docket number (country=us, exact)</td></tr><tr><td class=\"mono\">statutes_cited</td><td class=\"mono dim\">keyword · eq any</td><td>Statutes cited (country=us, as written)</td></tr><tr><td class=\"mono\">issue_tags</td><td class=\"mono dim\">keyword · eq any</td><td>Issue tags (country=us, open model-generated labels)</td></tr><tr><td class=\"mono\">party_names</td><td class=\"mono dim\">keyword · eq any</td><td>Party names (country=us)</td></tr><tr><td class=\"mono\">standard_of_review</td><td class=\"mono dim\">keyword · eq any</td><td>Standard of review (country=us)</td></tr><tr><td class=\"mono\">holding_by</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">atria · gemma</span></td><td>Which model produced the holding (atria overrides gemma)</td></tr><tr><td class=\"mono\">citation_norm</td><td class=\"mono dim\">keyword · eq any</td><td>Normalised citation (country=us)</td></tr><tr><td class=\"mono\">tier</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">a · b</span></td><td>Layer (country=us): a = the 3.44M in the vector index; b = the long tail, Postgres only</td></tr><tr><td class=\"mono\">jurisdiction</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">F · FD · FS · S · SA · ST</span></td><td>Jurisdiction code (country=us, CourtListener: F / FD / FS / S / SA / ST)</td></tr></tbody></table></div></details>","zh":"混合检索,每条命中一张卡片。2 credits。免费样例:<code>网络刷单诈骗 未遂</code>。<h4 class=\"sub\">过滤字段</h4><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>字段</th><th>类型 · op</th><th>含义</th></tr></thead><tbody><tr><td class=\"mono\">country</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">cn · us</span></td><td>cn(默认,中国裁判文书)/ us(美国判例)。两边字段不同:下面带 (country=us) 的只对美国生效,其余只对中国生效</td></tr><tr><td class=\"mono\">nature</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">criminal · civil · all</span></td><td>criminal / civil / all(默认 all,仅 country=cn)</td></tr><tr><td class=\"mono\">cause</td><td class=\"mono dim\">keyword · eq any</td><td>案由/罪名,精确匹配(见 facets crimes)</td></tr><tr><td class=\"mono\">province</td><td class=\"mono dim\">keyword · eq any</td><td>省份</td></tr><tr><td class=\"mono\">judge_year</td><td class=\"mono dim\">integer · range</td><td>裁判年份区间</td></tr><tr><td class=\"mono\">law_refs</td><td class=\"mono dim\">keyword · eq any</td><td>引用法条枢纽键,如 CN/刑法/266</td></tr><tr><td class=\"mono\">verdictno</td><td class=\"mono dim\">keyword · eq any</td><td>案号精确匹配(country=cn,如 (2023)湘0902刑初105号);查案号请用这个字段,不要放进 query——PG 层只分中文词,案号里的字母数字会被忽略</td></tr><tr><td class=\"mono\">articles</td><td class=\"mono dim\">keyword · eq any</td><td>引用法条精确到条(country=cn,全称 + 中文条号:中华人民共和国刑法 第二百六十四条)</td></tr><tr><td class=\"mono\">amount_max</td><td class=\"mono dim\">integer · range</td><td>判决涉及的最大金额区间(country=cn,单位元)</td></tr><tr><td class=\"mono\">year</td><td class=\"mono dim\">integer · eq range</td><td>裁判年份区间(country=us)</td></tr><tr><td class=\"mono\">proceeding_type</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">civil · criminal · administrative · bankruptcy · habeas_or_post_conviction · attorney_discipline · juvenile · other</span></td><td>程序类型(country=us)</td></tr><tr><td class=\"mono\">subject_areas</td><td class=\"mono dim\">keyword · eq any</td><td>法律领域(country=us,闭集 23 类:tort / contract / property / constitutional / employment …)</td></tr><tr><td class=\"mono\">disposition</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">affirmed · affirmed_in_part · reversed · reversed_and_remanded · vacated · vacated_and_remanded <span class=\"dim\">…共 12 个,/facets 可列全</span></span></td><td>处理结果(country=us,闭集 12 类)</td></tr><tr><td class=\"mono\">prevailing_party</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">appellant_or_plaintiff · appellee_or_defendant · mixed · unclear</span></td><td>胜诉方(country=us)</td></tr><tr><td class=\"mono\">precedential_status</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">Published · Unpublished · Relating-to · Separate · In-chambers · Errata · Unknown</span></td><td>是否公开判例(country=us)</td></tr><tr><td class=\"mono\">cite_count</td><td class=\"mono dim\">integer · eq range</td><td>被引次数区间(country=us)</td></tr></tbody></table></div><details class=\"adv\"><summary>还有 25 个,照样能用</summary><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>字段</th><th>类型 · op</th><th>含义</th></tr></thead><tbody><tr><td class=\"mono\">city</td><td class=\"mono dim\">keyword · eq any</td><td>城市</td></tr><tr><td class=\"mono\">court_level</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">基层 · 中级 · 高级 · 最高 · 专门 · scotus <span class=\"dim\">…共 17 个,/facets 可列全</span></span></td><td>审级。country=cn:基层 / 中级 / 高级 / 最高 / 专门;country=us:scotus / fed_appellate / fed_district / state_supreme / state_appellate …</td></tr><tr><td class=\"mono\">trial_round</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">一审 · 二审 · 再审</span></td><td>一审 / 二审 / 再审</td></tr><tr><td class=\"mono\">decided_at</td><td class=\"mono dim\">datetime · range</td><td>裁判日期区间</td></tr><tr><td class=\"mono\">laws</td><td class=\"mono dim\">keyword · eq any</td><td>引用法名简称,如 刑法</td></tr><tr><td class=\"mono\">sentence_type</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">有期徒刑 · 拘役 · 管制 · 无期徒刑 · 死刑 · 免予刑事处罚 · 单处罚金</span></td><td>有期徒刑 / 拘役 / 管制 / 无期徒刑 / 死刑 / 免予刑事处罚 / 单处罚金</td></tr><tr><td class=\"mono\">sentence_months</td><td class=\"mono dim\">integer · range</td><td>刑期(月)区间</td></tr><tr><td class=\"mono\">probation</td><td class=\"mono dim\">bool · eq</td><td>是否缓刑</td></tr><tr><td class=\"mono\">fine_amount</td><td class=\"mono dim\">integer · range</td><td>罚金(元)区间</td></tr><tr><td class=\"mono\">law_names</td><td class=\"mono dim\">keyword · eq any</td><td>引用法律全称(country=cn,如 中华人民共和国刑法;与 laws 的简称口径不同)</td></tr><tr><td class=\"mono\">org_parties</td><td class=\"mono dim\">keyword · eq any</td><td>法人或其他组织当事人名(country=cn)。自然人姓名不提供筛选</td></tr><tr><td class=\"mono\">status</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">生效 · 发回重审 · 终结执行 · 其他</span></td><td>文书状态(country=cn):生效 / 发回重审 / 终结执行 / 其他。只有 v2 行有值(约 204 万篇)</td></tr><tr><td class=\"mono\">district</td><td class=\"mono dim\">keyword · eq any</td><td>区县(country=cn,没有索引,筛选较慢)</td></tr><tr><td class=\"mono\">circumstance_tags</td><td class=\"mono dim\">keyword · eq any</td><td>量刑情节:自首 / 立功 / 累犯 / 坦白 / 认罪认罚 / 退赃退赔 / 谅解 / 从犯 / 主犯 / 未遂 / 未成年 / 前科 …</td></tr><tr><td class=\"mono\">procedural_posture</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">appeal_from_final_judgment · appeal_from_conviction · interlocutory_appeal · certiorari · petition_for_review · motion_ruling <span class=\"dim\">…共 11 个,/facets 可列全</span></span></td><td>审理阶段(country=us)</td></tr><tr><td class=\"mono\">court_id</td><td class=\"mono dim\">keyword · eq any</td><td>法院 id(country=us,CourtListener 口径,如 ca4 / scotus)</td></tr><tr><td class=\"mono\">docket_number</td><td class=\"mono dim\">keyword · eq any</td><td>案号(country=us,精确)</td></tr><tr><td class=\"mono\">statutes_cited</td><td class=\"mono dim\">keyword · eq any</td><td>引用的法条(country=us,原文写法)</td></tr><tr><td class=\"mono\">issue_tags</td><td class=\"mono dim\">keyword · eq any</td><td>争点标签(country=us,模型生成的开放标签)</td></tr><tr><td class=\"mono\">party_names</td><td class=\"mono dim\">keyword · eq any</td><td>当事人(country=us)</td></tr><tr><td class=\"mono\">standard_of_review</td><td class=\"mono dim\">keyword · eq any</td><td>审查标准(country=us)</td></tr><tr><td class=\"mono\">holding_by</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">atria · gemma</span></td><td>holding 由哪个模型给出(atria 覆盖过 gemma)</td></tr><tr><td class=\"mono\">citation_norm</td><td class=\"mono dim\">keyword · eq any</td><td>规范化引用号(country=us,如 956 F.2d 36)</td></tr><tr><td class=\"mono\">tier</td><td class=\"mono dim\">keyword · eq<span class=\"vals\">a · b</span></td><td>分层(country=us):a = 在向量索引里的 344 万篇;b = 只在 PG 里的长尾</td></tr><tr><td class=\"mono\">jurisdiction</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">F · FD · FS · S · SA · ST</span></td><td>法域代码(country=us,CourtListener 口径:F 联邦 / FD 联邦地区 / S 州 / SA 州上诉 …)</td></tr></tbody></table></div></details>"},"params":[{"name":"query","type":"string","required":true,"in":"body","example":"网络刷单诈骗 未遂","desc":{"en":"1–1000 characters. Or an array of up to 5 (batch; hits become results[]).","zh":"1–1000 字符。也可以是最多 5 条的数组(批量,hits 变 results[])。"}},{"name":"top_k","type":"integer","default":"10","in":"body","desc":{"en":"1–100.","zh":"1–100。"}},{"name":"fields","type":"enum","options":["brief","head"],"default":"brief","in":"body","desc":{"en":"head costs one more credit and returns the head view per hit.","zh":"head 多扣 1 credit,每条附 head 视图。"}},{"name":"filters","type":"json","in":"body","example":"","desc":{"en":"Filter DSL object (see Getting started); declared fields are listed above.","zh":"过滤 DSL 对象(见快速开始);可用字段见上表。"}},{"name":"mode","type":"enum","options":["hybrid","dense","bm25"],"default":"hybrid","in":"body","advanced":false,"desc":{"en":"Retrieval mode. Leave it out to use the first.","zh":"检索模式。不传就用第一个。"}},{"name":"offset","type":"integer","default":"0","in":"body","advanced":true,"desc":{"en":"Pagination.","zh":"翻页。"}}],"example":"{ \"domain\": \"cases\", \"query\": \"…\", \"hits\": [ { \"id\": \"8a1c3791-0cce-4094-9b28-a9a600b657c7\", \"score\": 0.83, \"brief\": { … } } ], \"total\": null, \"coverage\": …, \"warnings\": [],\n \"meta\": { \"request_id\": \"req_…\", \"credits\": { \"charged\": 2, \"balance\": 1998, \"pool\": \"allowance\" }, \"latency_ms\": 41, \"cached\": false } }","notes":[{"html":{"en":"<b>Undeclared filter fields return 400</b> rather than being ignored silently. Filters combine with AND; <code>_or</code> / <code>_not</code> are available.","zh":"<b>用了未声明的过滤字段返回 400</b>,不会静默忽略。过滤条件是 AND;可用 <code>_or</code> / <code>_not</code>。"}}]},{"id":"cases-read","domain":"cases","method":"GET","path":"/v1/cases/read/{uuid}","auth":"optional","status":"live","title":{"en":"Read","zh":"读"},"summary":{"en":"Three depths. <code>detail</code> is the default. Free sample: <code>8a1c3791-0cce-4094-9b28-a9a600b657c7</code>.<h4 class=\"sub\">Levels</h4><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>level</th><th>credits</th><th>returns</th></tr></thead><tbody><tr><td class=\"mono\">brief</td><td class=\"mono num\">1</td><td>Card (~150 tok): case number, cause, court, level, date, one-line summary, disputed issues, cited articles, sentencing</td></tr><tr><td class=\"mono\">detail <span class=\"dim\">(default)</span></td><td class=\"mono num\">2</td><td>Every structured field (~500 tok): claims, disputed issues, facts, circumstances, reasoning, outcome, parties, articles, amounts</td></tr><tr><td class=\"mono\">full <span class=\"gr-tag\" title=\"cases:fulltext\">permission</span></td><td class=\"mono num\">5</td><td>Full text (mean 2.5k chars, p95 5.5k). Needs the cases:fulltext grant</td></tr></tbody></table></div><h4 class=\"sub\">Extras</h4><p>One side of the same document, in place of a level.</p><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>extra</th><th>credits</th><th>returns</th></tr></thead><tbody><tr><td class=\"mono\">laws</td><td class=\"mono num\">2</td><td>Articles the judgment cites, with readable law links</td></tr></tbody></table></div>","zh":"三档深浅,不传就是 <code>detail</code>。免费样例:<code>8a1c3791-0cce-4094-9b28-a9a600b657c7</code>。<h4 class=\"sub\">三档</h4><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>深浅</th><th>credits</th><th>返回</th></tr></thead><tbody><tr><td class=\"mono\">brief</td><td class=\"mono num\">1</td><td>卡片(~150 tok):案号、案由、法院、审级、日期、一句话、争议焦点、法条、量刑</td></tr><tr><td class=\"mono\">detail <span class=\"dim\">(默认)</span></td><td class=\"mono num\">2</td><td>全部结构化字段(~500 tok):指控/争议焦点/事实/情节/说理/判项/当事人/法条/金额</td></tr><tr><td class=\"mono\">full <span class=\"gr-tag\" title=\"cases:fulltext\">需授权</span></td><td class=\"mono num\">5</td><td>全文(均值 2.5k 字,p95 5.5k)。需 cases:fulltext 授权</td></tr></tbody></table></div><h4 class=\"sub\">侧面</h4><p>同一份文档的另一个侧面,与 level 二选一。</p><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>侧面</th><th>credits</th><th>返回</th></tr></thead><tbody><tr><td class=\"mono\">laws</td><td class=\"mono num\">2</td><td>判决引用的法条,带可直接读的 law 链接</td></tr></tbody></table></div>"},"params":[{"name":"uuid","type":"string","required":true,"in":"path","example":"8a1c3791-0cce-4094-9b28-a9a600b657c7","desc":{"en":"Document id (uuid).","zh":"文档 id(uuid)。"}},{"name":"level","type":"enum","options":["brief","detail","full"],"default":"detail","desc":{"en":"How deep to read.","zh":"读多深。"}},{"name":"extra","type":"enum","options":["","laws"],"desc":{"en":"Read one side instead of a level.","zh":"改读某个侧面,与 level 二选一。"}},{"name":"format","type":"enum","options":["json","md","html"],"default":"json","desc":{"en":"Response shape.","zh":"响应形态。"}},{"name":"section","type":"string","required":false,"desc":{"en":" (level = full: read one section) Needs the cases:fulltext permission.","zh":" (level = full:只读这一节)需 cases:fulltext 授权。"},"when":{"param":"level","values":["full"]},"example":"opinion"},{"name":"characters","type":"integer","default":"3000","required":false,"desc":{"en":" (level = full: first N characters) Needs the cases:fulltext permission.","zh":" (level = full:只读前 N 字)需 cases:fulltext 授权。"},"when":{"param":"level","values":["full"]}}],"example":"{ \"domain\": \"cases\", \"id\": \"8a1c3791-0cce-4094-9b28-a9a600b657c7\", \"level\": \"detail\", \"view\": \"head\", \"data\": { … } | \"text\": \"…\", \"token_count\": 1834, \"meta\": { … } }","notes":[{"html":{"en":"<b><code>cases:fulltext</code> is a permission on the key, not a domain.</b> Verbatim text of Chinese judgments (whole, by section, or first N characters). Off by default: the originals carry party names, dates of birth and home addresses (58% of a 400-judgment sample had an unmasked name). level=detail already has every extracted field. Everything marked <i>permission</i> is a 403 without it and costs nothing — an empty scope list means every domain, never a permission. Ask for it on the API keys page in the console.","zh":"<b><code>cases:fulltext</code> 是 key 上的一个授权,不是垂域。</b>中国判决的正文(整篇 / 分段 / 前 N 字)。默认不开:裁判文书原文带当事人姓名、出生日期和住址,抽样 400 篇里 58% 有未脱敏真名。不需要正文的话 level=detail 已经有全部抽取字段。标了「需授权」的地方没有它就是 403,也不扣费——空 scopes 等于所有垂域,但不含任何授权。要开通去控制台的 API keys 页申请。"}},{"html":{"en":"The older <code>GET /v1/cases/doc/{id}?view=…</code> still works.","zh":"旧写法 <code>GET /v1/cases/doc/{id}?view=…</code> 仍然可用。"}}]},{"id":"cases-read-batch","domain":"cases","method":"POST","path":"/v1/cases/read","auth":"token","status":"live","title":{"en":"Read many","zh":"批量读"},"summary":{"en":"Up to 50 ids, one level. Missing ids come back with <code>error: \"not_found\"</code> and are not charged.","zh":"最多 50 个 id,同一档。查不到的 id 返回 <code>error: \"not_found\"</code>,不扣费。"},"params":[{"name":"ids","type":"array","list":true,"required":true,"in":"body","example":"8a1c3791-0cce-4094-9b28-a9a600b657c7, us:577203","desc":{"en":"Document ids.","zh":"文档 id 列表。"}},{"name":"level","type":"enum","options":["brief","detail","full"],"default":"detail","in":"body","desc":{"en":"Level for every id.","zh":"所有 id 共用的档。"}},{"name":"extra","type":"enum","options":["","laws"],"in":"body","desc":{"en":"Read one side instead.","zh":"改读某个侧面。"}}],"example":"{ \"domain\": \"cases\", \"level\": \"detail\", \"docs\": [ { \"id\": \"…\", \"data\": { … } }, { \"id\": \"…\", \"error\": \"not_found\" } ], \"meta\": { … } }"},{"id":"cases-facets","domain":"cases","method":"GET","path":"/v1/cases/facets","auth":"none","status":"live","title":{"en":"Facets","zh":"Facets"},"summary":{"en":"Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.","zh":"某个过滤字段的合法值,agent 不用猜;预聚合字段带计数,声明的枚举没有。免费、不需要 key。"},"params":[{"name":"field","type":"enum","options":["cause","province","court_level","trial_round","sentence_type","circumstance_tags","proceeding_type","subject_areas","disposition","prevailing_party","precedential_status","procedural_posture"],"required":true,"example":"cause","desc":{"en":"Filter field with facets.","zh":"有 facets 的过滤字段。"}},{"name":"limit","type":"integer","default":"50","advanced":true,"desc":{"en":"Max values.","zh":"最多返回多少个值。"}}],"example":"{ \"domain\": \"cases\", \"field\": \"…\", \"values\": [ { \"value\": \"…\", \"count\": 3120 } ], \"meta\": { … } }"},{"id":"cases-ask","domain":"cases","method":"POST","path":"/v1/cases/ask","auth":"registered","status":"live","stream":true,"agentic":true,"title":{"en":"Ask","zh":"问"},"summary":{"en":"Q&A over judgments: served by the same agent as the law domain (which already combines 'find the governing articles, then see how comparable judgments ruled'); scope defaults to case, i.e. judgments only. Answers cite [case number], with sources.cases / coverage as in law. <code>effort</code> low / medium / high = 50 / 100 / 200 credits. Append <code>/stream</code> for NDJSON; the first event is always <code>billing</code>. A failure before the first <code>answer_delta</code> is refunded.","zh":"判决问答:走 law 域的同一个 agent(它本来就是「先找依据条文、再看同类判决怎么判」的联合形态),默认 scope=case 只查判决;回答带 [案号] 引用,sources.cases / coverage 同 law。<code>effort</code> low / medium / high 对应 50 / 100 / 200 credits。加 <code>/stream</code> 走 NDJSON,第一个事件一定是 <code>billing</code>。首个 <code>answer_delta</code> 之前失败会退款。"},"params":[{"name":"query","type":"string","required":true,"in":"body","example":"网络刷单诈骗 未遂","desc":{"en":"1–2000 characters. Be specific; ask for numbers if you want numbers.","zh":"1–2000 字符。问得具体;要数字就直接问数字。"}},{"name":"scope","type":"enum","options":["auto","law","case","both"],"default":"case","required":false,"desc":{"en":"judgments only (default) / statutes too","zh":"只查判决(默认)/ 连法条一起查"},"in":"body"},{"name":"effort","type":"enum","options":["low","medium","high"],"default":"low","in":"body","desc":{"en":"Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it.","zh":"检索轮数,也决定价格:50 / 100 / 200 credits。套餐限制最高档。"}},{"name":"verbose","type":"bool","default":"false","in":"body","desc":{"en":"Include the tool-call trace (tool_call / tool_result / thinking events when streaming).","zh":"返回工具调用轨迹(流式时多 tool_call / tool_result / thinking 事件)。"}},{"name":"top_k","type":"integer","default":"10","in":"body","advanced":true,"desc":{"en":"Speculative prefetch size.","zh":"预取候选数。"}},{"name":"stream_answer","type":"bool","default":"true","in":"body","advanced":true,"desc":{"en":"Streaming only: false emits one answer event instead of deltas.","zh":"仅流式:false 时只发一个 answer 事件。"}},{"name":"max_rounds","type":"integer","in":"body","advanced":true,"desc":{"en":"0–8, overrides the effort preset.","zh":"0–8,覆盖 effort 预设。"}},{"name":"force_answer_after","type":"number","in":"body","advanced":true,"desc":{"en":"Seconds; hard cutover into the answer phase.","zh":"秒;强制切入作答阶段。"}},{"name":"max_answer_tokens","type":"integer","default":"4096","in":"body","advanced":true,"desc":{"en":"Hitting it sets answer_truncated.","zh":"触顶时置 answer_truncated。"}},{"name":"language","type":"string","in":"body","advanced":true,"desc":{"en":"Answer language; defaults to the query’s.","zh":"回答语言,默认跟随 query。"}}],"example":"{ \"answer\": \"… [(2018)闽0181刑初1319号] …\", \"sources\": [ … ], \"stats\": { \"rounds\": 1, \"elapsed_s\": 6.2, \"answer_truncated\": false }, \"coverage\"?: { … }, \"meta\": { \"credits\": { \"charged\": 50, … } } }","notes":[{"html":{"en":"<b>Answers can name people.</b> The verbatim judgment needs the <code>cases:fulltext</code> permission, but the extracted fields it reads do not, and the parties are named there — so an answer may carry the name of a natural person. Treat what comes back as personal data.","zh":"<b>回答里可能出现人名。</b>判决正文要 <code>cases:fulltext</code> 授权,但它读的抽取字段不需要,而当事人姓名就在抽取字段里——所以答案里可能带着自然人姓名。拿到的内容按个人信息对待。"}},{"html":{"en":"<b>Citations are real</b> — every id in <code>answer</code> exists in this domain (format <code>[(2018)闽0181刑初1319号]</code>). <b><code>sources</code> is the retrieval set</b>, not the citation list. <b><code>answer_truncated</code> means incomplete.</b>","zh":"<b>引用是真的</b>——<code>answer</code> 里的每个 id 都存在于本垂域(格式 <code>[(2018)闽0181刑初1319号]</code>)。<b><code>sources</code> 是召回集</b>,不是引用列表。<b><code>answer_truncated</code> 表示不完整。</b>"}}]},{"id":"us_law-search","domain":"us_law","method":"POST","path":"/v1/us_law/search","auth":"optional","status":"live","title":{"en":"Search","zh":"检索"},"summary":{"en":"Hybrid retrieval, one card per hit. 2 credits. Free sample: <code>HIPAA patient records disclosure</code>.<h4 class=\"sub\">Filter fields</h4><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>field</th><th>type · ops</th><th>meaning</th></tr></thead><tbody><tr><td class=\"mono\">jurisdiction</td><td class=\"mono dim\">keyword · eq any</td><td>Jurisdiction: federal or a two-letter state code (53 in all)</td></tr><tr><td class=\"mono\">is_federal</td><td class=\"mono dim\">bool · eq</td><td>Federal</td></tr><tr><td class=\"mono\">doc_group</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">statute · regulation · session_law · decision · proposed_regulation · guidance · court_rule · constitution · presidential · treaty</span></td><td>Document group</td></tr><tr><td class=\"mono\">kind</td><td class=\"mono dim\">keyword · eq any</td><td>Specific kind (see facets)</td></tr><tr><td class=\"mono\">status</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">in_force · superseded · enacted · repealed · proposed · reserved <span class=\"dim\">… 12 values, /facets lists them all</span></span></td><td>Status</td></tr><tr><td class=\"mono\">norm_types</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">obligation · prohibition · permission_or_authority · definition · procedure · eligibility_or_criteria <span class=\"dim\">… 15 values, /facets lists them all</span></span></td><td>Norm type (closed set of 15, model-assigned)</td></tr><tr><td class=\"mono\">has_penalty</td><td class=\"mono dim\">bool · eq</td><td>Carries a penalty</td></tr></tbody></table></div><details class=\"adv\"><summary>5 more, all usable</summary><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>field</th><th>type · ops</th><th>meaning</th></tr></thead><tbody><tr><td class=\"mono\">penalty_types</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">fine · civil_penalty · imprisonment · license_sanction · forfeiture · other</span></td><td>Penalty type</td></tr><tr><td class=\"mono\">citation</td><td class=\"mono dim\">keyword · eq any</td><td>Citation (exact, e.g. 42 C.F.R. § 2.33)</td></tr><tr><td class=\"mono\">subjects</td><td class=\"mono dim\">keyword · eq any</td><td>Subjects (open model-generated labels, very high cardinality)</td></tr><tr><td class=\"mono\">defined_terms</td><td class=\"mono dim\">keyword · eq any</td><td>Terms defined in this provision</td></tr><tr><td class=\"mono\">regulated_parties</td><td class=\"mono dim\">keyword · eq any</td><td>Regulated parties</td></tr></tbody></table></div></details>","zh":"混合检索,每条命中一张卡片。2 credits。免费样例:<code>HIPAA patient records disclosure</code>。<h4 class=\"sub\">过滤字段</h4><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>字段</th><th>类型 · op</th><th>含义</th></tr></thead><tbody><tr><td class=\"mono\">jurisdiction</td><td class=\"mono dim\">keyword · eq any</td><td>法域:federal 或州两字码(ca / tx / ny …,共 53 个)</td></tr><tr><td class=\"mono\">is_federal</td><td class=\"mono dim\">bool · eq</td><td>是否联邦</td></tr><tr><td class=\"mono\">doc_group</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">statute · regulation · session_law · decision · proposed_regulation · guidance · court_rule · constitution · presidential · treaty</span></td><td>文本大类</td></tr><tr><td class=\"mono\">kind</td><td class=\"mono dim\">keyword · eq any</td><td>细分类型(statutes / regulations / cfr_annual / ag_opinion …见 facets)</td></tr><tr><td class=\"mono\">status</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">in_force · superseded · enacted · repealed · proposed · reserved <span class=\"dim\">…共 12 个,/facets 可列全</span></span></td><td>效力状态</td></tr><tr><td class=\"mono\">norm_types</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">obligation · prohibition · permission_or_authority · definition · procedure · eligibility_or_criteria <span class=\"dim\">…共 15 个,/facets 可列全</span></span></td><td>规范类型(闭集 15 类,模型判定)</td></tr><tr><td class=\"mono\">has_penalty</td><td class=\"mono dim\">bool · eq</td><td>是否含罚则</td></tr></tbody></table></div><details class=\"adv\"><summary>还有 5 个,照样能用</summary><div class=\"tblwrap\"><table class=\"tbl t3\"><thead><tr><th>字段</th><th>类型 · op</th><th>含义</th></tr></thead><tbody><tr><td class=\"mono\">penalty_types</td><td class=\"mono dim\">keyword · eq any<span class=\"vals\">fine · civil_penalty · imprisonment · license_sanction · forfeiture · other</span></td><td>罚则类型</td></tr><tr><td class=\"mono\">citation</td><td class=\"mono dim\">keyword · eq any</td><td>引用号(精确,如 42 C.F.R. § 2.33)</td></tr><tr><td class=\"mono\">subjects</td><td class=\"mono dim\">keyword · eq any</td><td>主题(模型生成的开放标签,基数很大)</td></tr><tr><td class=\"mono\">defined_terms</td><td class=\"mono dim\">keyword · eq any</td><td>本条定义的术语</td></tr><tr><td class=\"mono\">regulated_parties</td><td class=\"mono dim\">keyword · eq any</td><td>受约束主体</td></tr></tbody></table></div></details>"},"params":[{"name":"query","type":"string","required":true,"in":"body","example":"HIPAA patient records disclosure","desc":{"en":"1–1000 characters. Or an array of up to 5 (batch; hits become results[]).","zh":"1–1000 字符。也可以是最多 5 条的数组(批量,hits 变 results[])。"}},{"name":"top_k","type":"integer","default":"10","in":"body","desc":{"en":"1–100.","zh":"1–100。"}},{"name":"fields","type":"enum","options":["brief","head"],"default":"brief","in":"body","desc":{"en":"head costs one more credit and returns the head view per hit.","zh":"head 多扣 1 credit,每条附 head 视图。"}},{"name":"filters","type":"json","in":"body","example":"","desc":{"en":"Filter DSL object (see Getting started); declared fields are listed above.","zh":"过滤 DSL 对象(见快速开始);可用字段见上表。"}},{"name":"mode","type":"enum","options":["hybrid","dense","bm25"],"default":"hybrid","in":"body","advanced":false,"desc":{"en":"Retrieval mode. Leave it out to use the first.","zh":"检索模式。不传就用第一个。"}},{"name":"offset","type":"integer","default":"0","in":"body","advanced":true,"desc":{"en":"Pagination.","zh":"翻页。"}}],"example":"{ \"domain\": \"us_law\", \"query\": \"…\", \"hits\": [ { \"id\": \"uslaw:CFRANN_2024_T42_P2_S2_33\", \"score\": 0.83, \"brief\": { … } } ], \"total\": null, \"coverage\": …, \"warnings\": [],\n \"meta\": { \"request_id\": \"req_…\", \"credits\": { \"charged\": 2, \"balance\": 1998, \"pool\": \"allowance\" }, \"latency_ms\": 41, \"cached\": false } }","notes":[{"html":{"en":"<b>Undeclared filter fields return 400</b> rather than being ignored silently. Filters combine with AND; <code>_or</code> / <code>_not</code> are available.","zh":"<b>用了未声明的过滤字段返回 400</b>,不会静默忽略。过滤条件是 AND;可用 <code>_or</code> / <code>_not</code>。"}}]},{"id":"us_law-read","domain":"us_law","method":"GET","path":"/v1/us_law/read/{law_id}","auth":"optional","status":"live","title":{"en":"Read","zh":"读"},"summary":{"en":"Three depths. <code>detail</code> is the default. Free sample: <code>uslaw:CFRANN_2024_T42_P2_S2_33</code>.<h4 class=\"sub\">Levels</h4><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>level</th><th>credits</th><th>returns</th></tr></thead><tbody><tr><td class=\"mono\">brief</td><td class=\"mono num\">1</td><td>Card: the fields needed to triage, same as in search hits</td></tr><tr><td class=\"mono\">detail <span class=\"dim\">(default)</span></td><td class=\"mono num\">2</td><td>Every structured field (rule-derived plus model-generated; model fields are listed in _enrich.fields)</td></tr><tr><td class=\"mono\">full</td><td class=\"mono num\">5</td><td>Full text (not available yet: the provision text lives on NAS (open_us_law); the index carries the summary plus an excerpt)</td></tr></tbody></table></div>","zh":"三档深浅,不传就是 <code>detail</code>。免费样例:<code>uslaw:CFRANN_2024_T42_P2_S2_33</code>。<h4 class=\"sub\">三档</h4><div class=\"tblwrap\"><table class=\"tbl t3 tnum\"><thead><tr><th>深浅</th><th>credits</th><th>返回</th></tr></thead><tbody><tr><td class=\"mono\">brief</td><td class=\"mono num\">1</td><td>卡片:做取舍够用的字段(检索结果里那张)</td></tr><tr><td class=\"mono\">detail <span class=\"dim\">(默认)</span></td><td class=\"mono num\">2</td><td>全部结构化字段(规则字段 + 模型字段,模型字段在 _enrich.fields 里列名)</td></tr><tr><td class=\"mono\">full</td><td class=\"mono num\">5</td><td>全文(建设中:条文全文在 NAS open_us_law,检索库里是摘要 + 节选(excerpt))</td></tr></tbody></table></div>"},"params":[{"name":"law_id","type":"string","required":true,"in":"path","example":"uslaw:CFRANN_2024_T42_P2_S2_33","desc":{"en":"Document id (law_id).","zh":"文档 id(law_id)。"}},{"name":"level","type":"enum","options":["brief","detail","full"],"default":"detail","desc":{"en":"How deep to read.","zh":"读多深。"}},{"name":"format","type":"enum","options":["json","md","html"],"default":"json","desc":{"en":"Response shape.","zh":"响应形态。"}}],"example":"{ \"domain\": \"us_law\", \"id\": \"uslaw:CFRANN_2024_T42_P2_S2_33\", \"level\": \"detail\", \"view\": \"head\", \"data\": { … } | \"text\": \"…\", \"token_count\": 1834, \"meta\": { … } }","notes":[{"html":{"en":"The older <code>GET /v1/us_law/doc/{id}?view=…</code> still works.","zh":"旧写法 <code>GET /v1/us_law/doc/{id}?view=…</code> 仍然可用。"}}]},{"id":"us_law-read-batch","domain":"us_law","method":"POST","path":"/v1/us_law/read","auth":"token","status":"live","title":{"en":"Read many","zh":"批量读"},"summary":{"en":"Up to 50 ids, one level. Missing ids come back with <code>error: \"not_found\"</code> and are not charged.","zh":"最多 50 个 id,同一档。查不到的 id 返回 <code>error: \"not_found\"</code>,不扣费。"},"params":[{"name":"ids","type":"array","list":true,"required":true,"in":"body","example":"uslaw:CFRANN_2024_T42_P2_S2_33","desc":{"en":"Document ids.","zh":"文档 id 列表。"}},{"name":"level","type":"enum","options":["brief","detail","full"],"default":"detail","in":"body","desc":{"en":"Level for every id.","zh":"所有 id 共用的档。"}}],"example":"{ \"domain\": \"us_law\", \"level\": \"detail\", \"docs\": [ { \"id\": \"…\", \"data\": { … } }, { \"id\": \"…\", \"error\": \"not_found\" } ], \"meta\": { … } }"},{"id":"us_law-facets","domain":"us_law","method":"GET","path":"/v1/us_law/facets","auth":"none","status":"live","title":{"en":"Facets","zh":"Facets"},"summary":{"en":"Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.","zh":"某个过滤字段的合法值,agent 不用猜;预聚合字段带计数,声明的枚举没有。免费、不需要 key。"},"params":[{"name":"field","type":"enum","options":["jurisdiction","doc_group","kind","status","norm_types","penalty_types"],"required":true,"example":"jurisdiction","desc":{"en":"Filter field with facets.","zh":"有 facets 的过滤字段。"}},{"name":"limit","type":"integer","default":"50","advanced":true,"desc":{"en":"Max values.","zh":"最多返回多少个值。"}}],"example":"{ \"domain\": \"us_law\", \"field\": \"…\", \"values\": [ { \"value\": \"…\", \"count\": 3120 } ], \"meta\": { … } }"},{"id":"us_law-ask","domain":"us_law","method":"POST","path":"/v1/us_law/ask","auth":"registered","status":"live","stream":true,"agentic":true,"title":{"en":"Ask","zh":"问"},"summary":{"en":"Agentic Q&A over this domain: the model turns the question into filters plus keywords from the domain's own self-description, reads the hits and answers with [us_law:<law_id> <title>] citations; /stream is NDJSON with real token deltas. <code>effort</code> low / medium / high = 50 / 100 / 200 credits. Append <code>/stream</code> for NDJSON; the first event is always <code>billing</code>. A failure before the first <code>answer_delta</code> is refunded.","zh":"本域的 agentic 问答:模型按自描述把问题翻成检索(筛选 + 关键词),读详情后作答,引用写成 [us_law:<law_id> <标题>];/stream 为 NDJSON,answer_delta 是边生成边发的真实片段。<code>effort</code> low / medium / high 对应 50 / 100 / 200 credits。加 <code>/stream</code> 走 NDJSON,第一个事件一定是 <code>billing</code>。首个 <code>answer_delta</code> 之前失败会退款。"},"params":[{"name":"query","type":"string","required":true,"in":"body","example":"HIPAA patient records disclosure","desc":{"en":"1–2000 characters. Be specific; ask for numbers if you want numbers.","zh":"1–2000 字符。问得具体;要数字就直接问数字。"}},{"name":"effort","type":"enum","options":["low","medium","high"],"default":"low","in":"body","desc":{"en":"Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it.","zh":"检索轮数,也决定价格:50 / 100 / 200 credits。套餐限制最高档。"}},{"name":"verbose","type":"bool","default":"false","in":"body","desc":{"en":"Include the tool-call trace (tool_call / tool_result / thinking events when streaming).","zh":"返回工具调用轨迹(流式时多 tool_call / tool_result / thinking 事件)。"}},{"name":"top_k","type":"integer","default":"10","in":"body","advanced":true,"desc":{"en":"Speculative prefetch size.","zh":"预取候选数。"}},{"name":"stream_answer","type":"bool","default":"true","in":"body","advanced":true,"desc":{"en":"Streaming only: false emits one answer event instead of deltas.","zh":"仅流式:false 时只发一个 answer 事件。"}},{"name":"max_rounds","type":"integer","in":"body","advanced":true,"desc":{"en":"0–8, overrides the effort preset.","zh":"0–8,覆盖 effort 预设。"}},{"name":"force_answer_after","type":"number","in":"body","advanced":true,"desc":{"en":"Seconds; hard cutover into the answer phase.","zh":"秒;强制切入作答阶段。"}},{"name":"max_answer_tokens","type":"integer","default":"4096","in":"body","advanced":true,"desc":{"en":"Hitting it sets answer_truncated.","zh":"触顶时置 answer_truncated。"}},{"name":"language","type":"string","in":"body","advanced":true,"desc":{"en":"Answer language; defaults to the query’s.","zh":"回答语言,默认跟随 query。"}}],"example":"{ \"answer\": \"… [42 C.F.R. § 2.33] …\", \"sources\": [ … ], \"stats\": { \"rounds\": 1, \"elapsed_s\": 6.2, \"answer_truncated\": false }, \"coverage\"?: { … }, \"meta\": { \"credits\": { \"charged\": 50, … } } }","notes":[{"html":{"en":"<b>Citations are real</b> — every id in <code>answer</code> exists in this domain (format <code>[42 C.F.R. § 2.33]</code>). <b><code>sources</code> is the retrieval set</b>, not the citation list. <b><code>answer_truncated</code> means incomplete.</b>","zh":"<b>引用是真的</b>——<code>answer</code> 里的每个 id 都存在于本垂域(格式 <code>[42 C.F.R. § 2.33]</code>)。<b><code>sources</code> 是召回集</b>,不是引用列表。<b><code>answer_truncated</code> 表示不完整。</b>"}}]}]</script> <script type="application/json" data-pg-strings>{"title":"Playground","host":"Base URL","hostGlobal":"worldwide","hostCn":"mainland China","relatedStocks":"Related stocks","hint":"Follows the section you are reading","token":"API token","tokenHint":"fa_live_… key · optional for free samples · stored in this browser only","tokenReq":"API key required (fa_live_…)","send":"Send request","stream":"Stream","response":"Response","events":"Events","answer":"Answer","sources":"Sources","cited":"cited","retrieved":"retrieved","stats":"Stats","coming":"This domain is still building. The request shape is final; sending is disabled until it is live.","open":"Playground","close":"Close","tokens":"tokens","chars":"characters","truncated":"answer truncated","code":"Code","openTab":"Open in a new tab","report":"This one is wrong — report it","quotaHit":"Daily quota used up ({used} / {limit}, resets {reset}). It is a quota, not a rate limit, so retrying will not help: write to {mail} about {grant}.","rateHit":"Over your rpm. Retry in {n} s.","lang":"en","apiBase":"https://api.1stauthor.com","codeBase":"https://api.1stauthor.com","cnBase":"https://api.rag.ac.cn","keys":"/dashboard/keys/","fb":"/feedback/","contact":"tommy@chien.io"}</script> </aside> <button class="btn btn-primary pg-fab" data-pg-open type="button">Playground</button> <script type="module" src="/_astro/DocsShell.astro_astro_type_script_index_0_lang.DYyeo6-7.js"></script> </main> <script type="module" src="/_astro/Base.astro_astro_type_script_index_0_lang.BodBiRg5.js"></script> </body> </html>