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.
Search
POST/v1/law/search
Hybrid retrieval, one card per hit. 2 credits. Free sample:
诈骗罪 量刑.
Filter fields
| field | type · ops | meaning |
|---|
| jurisdiction | keyword · eq anyCHN · JPN · GBR · USA · DEU · KOR … 26 values, /facets lists them all | ISO3 jurisdiction, e.g. CHN / JPN / GBR / USA / DEU / KOR; several allowed |
| law_id | keyword · eq | Restrict to one statute: doc_id or Chinese title / short title |
| status | keyword · eq anyin_force · repealed · not_yet · unknown | in_force / repealed / not_yet / unknown |
6 more, all usable
| field | type · ops | meaning |
|---|
| scope | keyword · eqnational · all · local | national (default, no local regulations) / all / local |
| granularity | keyword · eqarticle · law | article (default, article-level hits) / law (which statute to look at) |
| law_type | keyword · eq anyact · code · regulation · ordinance · decree · judicial_interpretation · constitution · other | Instrument type |
| domain | keyword · eq any | Legal domain (domain_global id, see facets) |
| norm_type | keyword · eq anyprocedure · obligation · scope · permission · prohibition · penalty · definition · right · principle | Norm type: obligation / prohibition / penalty / permission / procedure / definition / scope … (see facets) |
| effective_at | datetime · range | Effective date range |
Parameters
| Parameter | Type | Description |
| query REQUIRED | string | 1–1000 characters. Or an array of up to 5 (batch; hits become results[]). |
| top_k | integer= 10 | 1–100. |
| fields | brief · head= brief | head costs one more credit and returns the head view per hit. |
| filters | json | Filter DSL object (see Getting started); declared fields are listed above. |
| mode | hybrid · dense · bm25= hybrid | Retrieval mode. Leave it out to use the first. |
| offset | integer= 0 | Pagination. |
Example
{ "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 } } Undeclared filter fields return 400 rather than being ignored silently. Filters combine with AND; _or / _not are available.
A hit id reads straight back: an article hit comes back as <law_id>~<n> (e.g. chn:law:中华人民共和国刑法~296), so GET /v1/law/doc/<hit.id> returns that article — no need to take the law apart and pass article yourself. (It used to be #, which a URL treats as a fragment and truncates.)
Read
GET/v1/law/read/{law_id}
Three depths.
detail is the default. Free sample:
刑法.
Levels
| level | credits | returns |
|---|
| brief | 1 | One statute's card: trilingual title, issuer, type, level, status, dates, one-liner, domains, article count |
| detail (default) | 2 | brief + summary, chapter tree (one line per chapter), key provisions, defined terms, obligations / penalties, typical questions, routing hints (~1–3k tok) |
| full | 5 | Full text, paged by article (offset / limit; see truncated / next_offset) |
Extras
One side of the same document, in place of a level.
| extra | credits | returns |
|---|
| cases | 2 | Article → judgments citing it: citation count + list (ranked by `query` if given, else newest first) |
Parameters
| Parameter | Type | Description |
| 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
| Parameter | Type | Description |
| 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
| Parameter | Type | Description |
| 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
| Parameter | Type | Description |
| 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).
Search
POST/v1/cases/search
Hybrid retrieval, one card per hit. 2 credits. Free sample:
网络刷单诈骗 未遂.
Filter fields
| field | type · ops | meaning |
|---|
| country | keyword · eqcn · us | 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 |
| nature | keyword · eqcriminal · civil · all | criminal / civil / all (default all; country=cn only) |
| cause | keyword · eq any | Cause of action / crime, exact match (see facets) |
| province | keyword · eq any | Province |
| judge_year | integer · range | Decision year range |
| law_refs | keyword · eq any | Cited article key, e.g. CN/刑法/266 |
| verdictno | keyword · eq any | Exact case number (country=cn). Use this filter rather than the query text: the Postgres layer tokenises Chinese only |
| articles | keyword · eq any | Cited provision, to the article (country=cn; full law name + Chinese article number) |
| amount_max | integer · range | Largest amount in the judgment, range (country=cn, CNY) |
| year | integer · eq range | Decision year, range (country=us) |
| proceeding_type | keyword · eq anycivil · criminal · administrative · bankruptcy · habeas_or_post_conviction · attorney_discipline · juvenile · other | Proceeding type (country=us) |
| subject_areas | keyword · eq any | Subject area (country=us, closed set of 23) |
| disposition | keyword · eq anyaffirmed · affirmed_in_part · reversed · reversed_and_remanded · vacated · vacated_and_remanded … 12 values, /facets lists them all | Disposition (country=us, closed set of 12) |
| prevailing_party | keyword · eq anyappellant_or_plaintiff · appellee_or_defendant · mixed · unclear | Prevailing party (country=us) |
| precedential_status | keyword · eq anyPublished · Unpublished · Relating-to · Separate · In-chambers · Errata · Unknown | Precedential status (country=us) |
| cite_count | integer · eq range | Citation count, range (country=us) |
25 more, all usable
| field | type · ops | meaning |
|---|
| city | keyword · eq any | City |
| court_level | keyword · eq any基层 · 中级 · 高级 · 最高 · 专门 · scotus … 17 values, /facets lists them all | Court level. country=cn: 基层 / 中级 / 高级 / 最高 / 专门; country=us: scotus / fed_appellate / fed_district / state_supreme / state_appellate … |
| trial_round | keyword · eq any一审 · 二审 · 再审 | Trial round |
| decided_at | datetime · range | Decision date range |
| laws | keyword · eq any | Cited statute short title, e.g. 刑法 |
| sentence_type | keyword · eq any有期徒刑 · 拘役 · 管制 · 无期徒刑 · 死刑 · 免予刑事处罚 · 单处罚金 | Sentence type |
| sentence_months | integer · range | Sentence length in months, range |
| probation | bool · eq | Probation granted |
| fine_amount | integer · range | Fine amount (CNY), range |
| law_names | keyword · eq any | Cited law, full name (country=cn; laws uses short names) |
| org_parties | keyword · eq any | Organisation party name (country=cn). Natural persons are not filterable |
| status | keyword · eq any生效 · 发回重审 · 终结执行 · 其他 | Document status (country=cn); only the ~2.04M v2 rows have it |
| district | keyword · eq any | District (country=cn; not indexed, slower) |
| circumstance_tags | keyword · eq any | Sentencing circumstances: 自首 / 立功 / 累犯 / 认罪认罚 / 退赃退赔 / 未遂 … |
| procedural_posture | keyword · eq anyappeal_from_final_judgment · appeal_from_conviction · interlocutory_appeal · certiorari · petition_for_review · motion_ruling … 11 values, /facets lists them all | Procedural posture (country=us) |
| court_id | keyword · eq any | Court id (country=us, CourtListener) |
| docket_number | keyword · eq any | Docket number (country=us, exact) |
| statutes_cited | keyword · eq any | Statutes cited (country=us, as written) |
| issue_tags | keyword · eq any | Issue tags (country=us, open model-generated labels) |
| party_names | keyword · eq any | Party names (country=us) |
| standard_of_review | keyword · eq any | Standard of review (country=us) |
| holding_by | keyword · eqatria · gemma | Which model produced the holding (atria overrides gemma) |
| citation_norm | keyword · eq any | Normalised citation (country=us) |
| tier | keyword · eqa · b | Layer (country=us): a = the 3.44M in the vector index; b = the long tail, Postgres only |
| jurisdiction | keyword · eq anyF · FD · FS · S · SA · ST | Jurisdiction code (country=us, CourtListener: F / FD / FS / S / SA / ST) |
Parameters
| Parameter | Type | Description |
| query REQUIRED | string | 1–1000 characters. Or an array of up to 5 (batch; hits become results[]). |
| top_k | integer= 10 | 1–100. |
| fields | brief · head= brief | head costs one more credit and returns the head view per hit. |
| filters | json | Filter DSL object (see Getting started); declared fields are listed above. |
| mode | hybrid · dense · bm25= hybrid | Retrieval mode. Leave it out to use the first. |
| offset | integer= 0 | Pagination. |
Example
{ "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 } } Undeclared filter fields return 400 rather than being ignored silently. Filters combine with AND; _or / _not are available.
Read
GET/v1/cases/read/{uuid}
Three depths.
detail is the default. Free sample:
8a1c3791-0cce-4094-9b28-a9a600b657c7.
Levels
| level | credits | returns |
|---|
| brief | 1 | Card (~150 tok): case number, cause, court, level, date, one-line summary, disputed issues, cited articles, sentencing |
| detail (default) | 2 | Every structured field (~500 tok): claims, disputed issues, facts, circumstances, reasoning, outcome, parties, articles, amounts |
| full permission | 5 | Full 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.
| extra | credits | returns |
|---|
| laws | 2 | Articles the judgment cites, with readable law links |
Parameters
| Parameter | Type | Description |
| 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
| Parameter | Type | Description |
| 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
| Parameter | Type | Description |
| 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
| Parameter | Type | Description |
| 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).
Search
POST/v1/us_law/search
Hybrid retrieval, one card per hit. 2 credits. Free sample:
HIPAA patient records disclosure.
Filter fields
| field | type · ops | meaning |
|---|
| jurisdiction | keyword · eq any | Jurisdiction: federal or a two-letter state code (53 in all) |
| is_federal | bool · eq | Federal |
| doc_group | keyword · eq anystatute · regulation · session_law · decision · proposed_regulation · guidance · court_rule · constitution · presidential · treaty | Document group |
| kind | keyword · eq any | Specific kind (see facets) |
| status | keyword · eq anyin_force · superseded · enacted · repealed · proposed · reserved … 12 values, /facets lists them all | Status |
| norm_types | keyword · eq anyobligation · prohibition · permission_or_authority · definition · procedure · eligibility_or_criteria … 15 values, /facets lists them all | Norm type (closed set of 15, model-assigned) |
| has_penalty | bool · eq | Carries a penalty |
5 more, all usable
| field | type · ops | meaning |
|---|
| penalty_types | keyword · eq anyfine · civil_penalty · imprisonment · license_sanction · forfeiture · other | Penalty type |
| citation | keyword · eq any | Citation (exact, e.g. 42 C.F.R. § 2.33) |
| subjects | keyword · eq any | Subjects (open model-generated labels, very high cardinality) |
| defined_terms | keyword · eq any | Terms defined in this provision |
| regulated_parties | keyword · eq any | Regulated parties |
Parameters
| Parameter | Type | Description |
| query REQUIRED | string | 1–1000 characters. Or an array of up to 5 (batch; hits become results[]). |
| top_k | integer= 10 | 1–100. |
| fields | brief · head= brief | head costs one more credit and returns the head view per hit. |
| filters | json | Filter DSL object (see Getting started); declared fields are listed above. |
| mode | hybrid · dense · bm25= hybrid | Retrieval mode. Leave it out to use the first. |
| offset | integer= 0 | Pagination. |
Example
{ "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 } } Undeclared filter fields return 400 rather than being ignored silently. Filters combine with AND; _or / _not are available.
Read
GET/v1/us_law/read/{law_id}
Three depths.
detail is the default. Free sample:
uslaw:CFRANN_2024_T42_P2_S2_33.
Levels
| level | credits | returns |
|---|
| brief | 1 | Card: the fields needed to triage, same as in search hits |
| detail (default) | 2 | Every structured field (rule-derived plus model-generated; model fields are listed in _enrich.fields) |
| full | 5 | Full text (not available yet: the provision text lives on NAS (open_us_law); the index carries the summary plus an excerpt) |
Parameters
| Parameter | Type | Description |
| 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
| Parameter | Type | Description |
| 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
| Parameter | Type | Description |
| 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. 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
| Parameter | Type | Description |
| query REQUIRED | string | 1–2000 characters. Be specific; ask for numbers if you want numbers. |
| 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": "… [42 C.F.R. § 2.33] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } Citations are real — every id in answer exists in this domain (format [42 C.F.R. § 2.33]). sources is the retrieval set, not the citation list. answer_truncated means incomplete.