---
name: 1stauthor-cases
description: Search and read Chinese court judgments through the 1stAuthor API — structured briefs, reasoning and outcome, and the articles each judgment relies on. Use when asked how courts actually decide a kind of case.
---

# 1stAuthor Law · Judgments

Court judgments: 17.49M from China (2.65M criminal plus 14.83M civil / administrative / enforcement) and 3.44M US opinions (country=us, tier A). Brief-level hybrid retrieval with LLM-extracted structured fields. Chinese judgment text needs the cases:fulltext grant (the originals carry personal data); US full text waits on the PG store.

Base URL `https://api.1stauthor.com`. Every call takes `Authorization: Bearer $FA_API_KEY`; the free samples named below work without a key. Free sample id: `8a1c3791-0cce-4094-9b28-a9a600b657c7`, free sample query: `网络刷单诈骗 未遂`.

## Three verbs, every domain

```
POST /v1/{domain}/search  {query, filters?, top_k?}      → hits[].id + a card each
GET  /v1/{domain}/read/{id}?level=brief|detail|full      → read as deep as you need
POST /v1/{domain}/ask     {query, effort: low|medium|high} → an answer with real citations
```

`read` also takes `extra=<side>` for another side of the same document and `format=json|md|html`.
At `level=full`, `section=<name>` reads one section and `characters=N` the first N characters.

## Start here

- **Find judgments** — `POST /v1/cases/search {"query": "网络刷单诈骗 未遂", "filters": {"province": "浙江省", "judge_year": {"gte": 2018}}}`
- **Read a judgment** — `GET /v1/cases/read/<uuid>`
- **Judgments citing an article** — `POST /v1/cases/search {"query": "…", "filters": {"law_refs": ["CN/刑法/266"]}}`
- **Find US opinions** — `POST /v1/cases/search {"query": "qualified immunity police", "filters": {"country": "us", "court_level": "scotus"}}`
- **Read a US opinion** — `GET /v1/cases/read/us:577203`

## Search filters

| field | type | meaning |
|---|---|---|
| `country` | keyword · eq | 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 · eq | 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 any | Proceeding type (country=us) |
| `subject_areas` | keyword · eq any | Subject area (country=us, closed set of 23) |
| `disposition` | keyword · eq any | Disposition (country=us, closed set of 12) |
| `prevailing_party` | keyword · eq any | Prevailing party (country=us) |
| `precedential_status` | keyword · eq any | Precedential status (country=us) |
| `cite_count` | integer · eq range | Citation count, range (country=us) |

Rarely needed, but valid: `city`, `court_level`, `trial_round`, `decided_at`, `laws`, `sentence_type`, `sentence_months`, `probation`, `fine_amount`, `law_names`, `org_parties`, `status`, `district`, `circumstance_tags`, `procedural_posture`, `court_id`, `docket_number`, `statutes_cited`, `issue_tags`, `party_names`, `standard_of_review`, `holding_by`, `citation_norm`, `tier`, `jurisdiction`.

Filters combine with AND; `_or` / `_not` are available. Ranges are `{"gte": n}` / `{"lte": n}`, full text is `{"text": "…"}`.

## Read

| 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` | 5 | Full text (mean 2.5k chars, p95 5.5k). Needs the cases:fulltext grant |

| extra | credits | returns |
|---|---|---|
| `laws` | 2 | Articles the judgment cites, with readable law links |

## Ask

`POST /v1/cases/ask {query, effort}` — 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. Costs 50 / 100 / 200 credits by effort. Append `/stream` for NDJSON; the first event is always `billing`.

`sources` is the retrieval set, not the citation list — filter it by the ids that appear in `answer`. `answer_truncated` means the answer is incomplete; say so.

## Also here



## Facets

`GET /v1/cases/facets?field=<field>` lists the legal values for `cause`, `province`, `court_level`, `trial_round`, `sentence_type`, `circumstance_tags`, `proceeding_type`, `subject_areas`, `disposition`, `prevailing_party`, `precedential_status`, `procedural_posture` — free, no key. Use it instead of guessing a spelling.

## Working rules

- **Search first, read second.** A search hit is a card; decide from the card which ids deserve a read.
- **Read in layers.** `detail` answers most questions; go to `full` only when the answer is not in it.
- **Filters are declared.** An undeclared filter field is a 400, never a silent no-op. `GET /v1/{domain}` lists what exists.
- **Cite what you read.** Use the citation format below, and say plainly when the corpus has nothing.
- **Failures are not charged.** A 404 costs nothing; an upstream error is refunded. Quote `meta.request_id` when reporting one.

Citation format: `[（2018）闽0181刑初1319号]`.

## What this corpus will and will not tell you

- 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).

---

Generated from https://api.1stauthor.com/v1/cases on 2026-10-14. Full reference: https://1stauthor.com/docs/law/