# OpenLaws API Integration Guide

> Index of all agent docs: https://openlaws.us/llms.txt
>
> A guide for engineers and coding agents integrating the OpenLaws API. **No legal background required:** section 2
> explains the legal research concepts the API is built around.
>
> **Scope:** codified law: statutes, regulations, constitutions, and court rules where a jurisdiction codifies them
> in its statutes or regulations. The endpoints in this guide don't return case law or court opinions; use a
> case-law provider such as CourtListener for those. Agency guidance, enforcement letters, and manuals are not
> covered either.

- **Base URL:** `https://api.openlaws.us`
- **Paths:** all under `/api/v1`
- **Format:** JSON
- **Auth:** `Authorization: Bearer <token>` (§5)
- **Schema source of truth:** the OpenAPI spec at https://openlaws.us/openapi.yaml. It lists every endpoint,
  parameter, and field; this guide explains how to use them well and uses only what the spec lists.
- **Changes:** the [release notes](https://docs.openlaws.us/development-guide/release-notes) list API changes by
  version.
- **The API is read-only.** No call changes data, so calls are safe to retry and to run in parallel.

> **If you learned this API before 2026-10:** search is no longer keyword-only, `type` has two Boolean values, and
> search results paginate. Read §3 and the spec before reusing old code or prompts.

---

## 1. The 30-second mental model

OpenLaws consolidates **53 jurisdictions** (the 50 states, DC, Puerto Rico, and federal) into **one schema**. Learn
it once and every jurisdiction works the same way.

```
Jurisdiction        a government whose law applies (FED, CA, NY…)
  └── Law           one body of law in that jurisdiction (FED-USC, CA-RR…)
        └── Division one addressable node of legal text (title, chapter, section…), arranged in a tree
```

You reach a Division three ways. Use the most precise one available:

1. **Citation lookup:** you have a citation → the exact provision (§4).
2. **Path lookup:** you have a Division `path` → that node, and you can walk up and down the tree.
3. **Search:** you have a topic → ranked candidates (§3).

A citation or path returns *the* answer; search returns *candidate* answers. Don't search for what you can address
directly.

---

## 2. Legal research for engineers

Search results only make sense once you know how legal research works. This section covers the concepts and the
order a law librarian works in.

### 2.1 Jurisdiction: which government's law

A **jurisdiction** is a government whose laws apply: the federal government, a state, DC, or Puerto Rico. Each has a
short **jurisdiction key**:

| Key | Jurisdiction |
|-----|--------------|
| `FED` | United States (federal) |
| `CA`, `NY`, `TX`, … | the 50 states, by USPS code |
| `DC` | District of Columbia |
| `PR` | Puerto Rico |

`US` is accepted as `FED`. Keys are case-insensitive.

There is no single "U.S. law". "How much notice before a rent increase?" has dozens of answers, and the federal
answer is often "that's a state matter". So:

- **Scope every search and lookup to a jurisdiction, in the URL.** There is no nationwide search. A Utah answer to a
  California question is worse than no answer.
- **Citation abbreviations collide across states,** so the jurisdiction also decides how a citation is read.
- **Many topics are regulated at both levels** (employment, environment, securities, consumer protection). Search the
  state and federal law (§3.8).
- **Never put the state name in the search query.** Search `scaffolding` under `NY`, not `new york scaffolding`.

If the jurisdiction is unknown, resolve it first. Don't guess.

### 2.2 Type of law: statute, regulation, constitution

Within a jurisdiction, a **Law** is one body of law, keyed `JURISDICTION-TYPE`. The suffix says what kind of law it
is, and it changes the answer:

| Suffix | Kind | Meaning | Examples |
|--------|------|---------|----------|
| `-STAT`, `-USC` | **Statute** | Passed by a legislature. Sets the rule. | `FL-STAT`, `FED-USC` |
| `-RR`, `-CFR` | **Regulation** | Issued by an agency under authority a statute gave it. Has the force of law and governs day-to-day conduct. | `CA-RR`, `FED-CFR` |
| `-CONST` | **Constitution** | The jurisdiction's foundational law. | `FED-CONST`, `NY-CONST` |
| `-CR` | **Court rules** | Rules of court that the jurisdiction codifies (§2.3). | `NY-CR` |

Other suffixes exist for smaller bodies of law, for example `FED-EO` (executive orders) and `PA-USTAT` (Pennsylvania's
unconsolidated statutes), and some keys carry a further qualifier (`AR-RR-PRE2025`). Discover the real list with
`GET /api/v1/jurisdictions/:jurisdiction_key/laws`; the `law_type` field there holds values such as `statutes`,
`regulations`, `constitution`, and `court_rules`.

> **Why this matters:** the answer to "what does the law require for X" usually lives in both the statute (the
> requirement) and the regulation (the operational detail). In advertising, licensing, and banking, a statute often
> sets the general rule, such as a ban on deceptive advertising, and regulations add the specifics: required
> disclosures, license conditions, filing deadlines. Searching only statutes can miss half the answer.

Division lookups by path accept two federal aliases for the law key: `FED-STAT` for `FED-USC` and `FED-RR` for
`FED-CFR`. Search does not accept them; use `FED-USC` and `FED-CFR` there.

### 2.3 Court rules

Court rules (civil procedure, evidence, criminal procedure, appellate practice) are in OpenLaws where the
jurisdiction codifies them in its statutes or regulations. Where they live varies:

- **Federal:** the Federal Rules of Civil Procedure, Evidence, Criminal Procedure, and Appellate Procedure are in the
  U.S. Code appendices, in `FED-USC`.
- **New York:** the CPLR is a statute, in `NY-STAT`. The court rules in title 22 of the NYCRR are in `NY-CR`.
- **Pennsylvania:** the court rules published in the Pennsylvania Code are in `PA-RR`.
- **Many states** codify their evidence or procedure rules as statutes (for example California's Evidence Code and
  Code of Civil Procedure, in `CA-STAT`).

Rule sets that exist only as court-issued rules are out of scope, for example the California Rules of Court and the
Texas Rules of Civil Procedure. A lookup for one of those finds nothing; say so rather than substituting a nearby
statute.

### 2.4 Division and `path`: the addressable unit

Legal text is a tree: titles → chapters → sections → subsections. Each node is a **Division** with a **`path`**, a
dotted lowercase address that encodes its place in the tree:

```
title_42.chapter_21.subchapter_i.section_1983
```

- Segments run broadest (left) to most specific (right), like folders.
- In URLs you may use slashes; the API converts `/` to `.`.
- **Don't build paths by hand.** Get them from the API (root divisions, `display_children`, `display_ancestors`,
  search hits) and navigate from there. Paths can move (§12).

### 2.5 Citations: the standard address of a provision

A **legal citation** is a compact, standardized reference to a provision. The dominant U.S. format is the
**Bluebook**. You don't need to learn it; recognize one and pass it to the citation endpoint (§4).

```
Cal. Gov't Code   §          12940
└─ the source ─┘  └ "section" ┘ └─ the section number
```

| Citation | Reads as |
|----------|----------|
| `42 U.S.C. § 1983` | Title 42 of the U.S. Code, section 1983 (federal statute) |
| `21 C.F.R. § 101.9` | Title 21 of the Code of Federal Regulations, section 101.9 (federal regulation) |
| `Fla. Stat. § 718.111` | Florida Statutes, section 718.111 |

`§` means "section" and `§§` "sections". A **pincite** points inside a section: `§ 12940(j)(1)` is subdivision
(j), paragraph (1).

### 2.6 The research process

Work through these steps in order. Each one changes which call you make.

1. **Jurisdiction.** Which state, and does federal law also govern the topic? (§2.1)
2. **Type of law.** Statute, regulation, constitution, or codified court rule? The operational detail is usually in
   a regulation, under a statute that sets the rule. (§2.2)
3. **Search method.** Legal research tools offer three: by citation, by natural language, and by terms and
   connectors (Boolean). OpenLaws offers the same three: citation lookup (§4), hybrid search (§3.5), and
   `type=terms_and_connectors` (§3.4), on top of plain keyword search.
4. **Context.** Read each result where it sits in the table of contents (`display_ancestors`). A section titled
   "Definitions" means little until you know it is under "Title 7: Agriculture".
5. **Definitions.** A term of art means what the code defines it to mean, which may differ from everyday usage.
   Codes usually define terms in a section at the start of the chapter or title. Find it and read it before
   interpreting the operative section.
6. **Cross-references and exceptions.** Follow "notwithstanding", "except as provided in", and references to other
   sections before concluding. A section is rarely the whole answer.
7. **Freshness.** Check `is_repealed`, the effective dates, and (on Enterprise Law Data API) `current_as_of` before
   relying on a provision.

**Treat the first search as a draft.** Judge how relevant the results are and adjust. Getting to the right provisions
usually takes several attempts.

### 2.7 Hierarchy of authority

- A constitution outranks a statute, and a statute outranks a regulation. A regulation implements the statute that
  authorizes it.
- Federal law can preempt conflicting state law. Some areas (immigration, patents) are federal regardless of what a
  state document says.
- So a provision can exist in the corpus and still be unenforceable. Existence is not validity.

### 2.8 Grounding and the advice boundary

- **Ground every answer in retrieved text.** Quote it, and give its citation and `openlaws_web_url` so a user can
  check it.
- **Never present a citation that no lookup returned.** Re-resolve any citation a model wrote from memory.
- **An empty result is a finding, with limits.** After several well-formed searches find nothing, report "no
  provision found in OpenLaws for these terms". That is weaker than "this is unregulated".
- **Show the law; don't advise.** Products built on this API should report what the provisions say and leave "what
  should I do" to a lawyer.

---

## 3. Search

### 3.1 How search matches

By default, search is **keyword search**: it finds the words of your query (and other forms of those words, §3.3) in
the text and ranks results by how well they match. It does not guess intent. Two other modes exist:

- **Terms and connectors** (`type=terms_and_connectors` or `strict_booleans`, §3.4): you write the match logic with
  AND, OR, NOT, parentheses, and quoted phrases.
- **Hybrid** (`hybrid_balance`, §3.5): blends in semantic matching, which finds text by meaning.

**Default strategy:** keyword search with synonym expansion (§3.2). Use terms and connectors to express synonym
groups in one query. Fall back to hybrid when expanded keyword searches miss.

### 3.2 Synonym expansion

Statutes and regulations rarely use the obvious word. The California regulation requiring workers' compensation
coverage contains neither "workers compensation" nor "insurance". The same concept also has different terms of art
in different jurisdictions. So you supply the vocabulary the law uses:

| Plain-language query | Terms of art to search |
|---|---|
| `can my landlord evict me without notice?` | `eviction notice` · `"notice to quit"` · `unlawful detainer` |
| `how much overtime pay am I owed` | `overtime wages` · `overtime compensation` |
| `new york scaffolding safety rules` | `scaffolding` (with `NY` in the URL) |

The recommended pattern:

1. Have a model list the concept's terms of art and synonyms, **specific to broad**: `recreational vehicle advertising
   price` → `recreational vehicle advertising` → `recreational vehicle`.
2. Run the variants **in parallel**, plus a federal search when the topic could be federal. The API is unmetered
   within the rate limits (§9).
3. Merge the results and **re-rank against your own context**. You know more about the matter than a keyword query
   does.
4. As the terms broaden, **discard off-topic hits more strictly**.

> **Keep queries to terms of art.** Leave out client names, case facts, stop words ("of", "the", "if"), and state
> names. The engine can't use them, and client facts shouldn't leave your system.

### 3.3 Word variations

- **Regular inflections match automatically.** `security deposit` and `security deposits` return the same results;
  `deposit` also matches "deposited". Don't add plural forms.
- **Irregular forms don't match each other.** `child labor` finds Texas Labor Code chapter 51 (Employment of
  Children); `children labor` finds unrelated sections. Write both forms: `child`, `children`.
- **Spelling variants don't match each other.** `email consent` and `e-mail consent` return different results. Write
  both.
- **Abbreviations:** include the spelled-out form, and the abbreviation with and without periods.

There is no wildcard (`*`) or root expander (`!`). Spell the variants out.

### 3.4 Query types (`type`)

| `type` | Matches | Use for |
|--------|---------|---------|
| `or` (default) | Any of the words, ranked | Exploring; plain-language questions |
| `and` | Every word | 2–4 precise terms |
| `phrase` | The words in that order (other word forms included) | Multi-word terms of art: `"notice to quit"` |
| `terms_and_connectors` | Boolean, Westlaw/Lexis style | Synonym groups and exclusions in one query |
| `strict_booleans` | Boolean, Lucene style | The same, Lucene syntax |

**The two Boolean types:**

- `terms_and_connectors`: `and`, `or`, `not`, `but not` in any case, plus `&` (AND) and `%` (NOT). Quote an operator
  word to search it as a word: `"search and seizure"`.
- `strict_booleans`: uppercase `AND`, `OR`, `NOT` only (lowercase are search words), plus `&&`, `||`, and a leading
  `-` or `!` for NOT: `eviction -commercial`.
- In both: NOT binds tightest, then AND, then OR. Adjacent words are ANDed. `( )` groups. `"quoted text"` is a
  phrase. Every match needs a positive term: `wages and not tips` works, `not tips` alone doesn't.
- Limits: 32 terms or phrases, 8 levels of nesting, 2,048 bytes.

Synonym expansion fits naturally here. Group synonyms with OR and join concepts with AND:

```
(minor or juvenile or child or children) and (employment or work) and not school
```

**Unsupported, with a teaching 400.** Proximity connectors (`/s`, `/p`, `w/5`), the `*` wildcard, the `!` root
expander, and field restrictors (`TI(…)`) are not supported. A query using them returns `400`: `title` names the
problem and `detail` gives the syntax plus a corrected query to try. To translate a query pasted from Westlaw or
Lexis, replace proximity with AND or a quoted phrase, and spell out the word endings a root expander would have
covered.

URL-encode `query`: an unencoded `&` ends the parameter.

### 3.5 Hybrid search (`hybrid_balance`)

`hybrid_balance` blends semantic matching, which finds text by meaning, into keyword search.

- `0` (default): keyword only.
- Between `0` and `1`: ranked by a blend. With `type=or`, a result can come from either side, so it may share no
  words with the query. With the other types, the query still decides what matches, and the balance only reorders
  the results.
- `1`: ranked by meaning alone. With `type=or`, the results are the closest by meaning, whatever words they contain.
  With the other types, a result must match the query and also be among the closest by meaning, so fewer results
  come back than at a lower balance.
- `auto`: picks a balance from the query, leaning semantic for longer plain-language questions and keyword for short
  queries, quoted phrases, citations, and Boolean types.

Response headers report what was applied: `Hybrid-Balance`, `Hybrid-Balance-Source` (`explicit` or `auto`), and
`Hybrid-Balance-Auto-Version`.

**When to use it:** as the fallback after synonym-expanded keyword searches miss, or for a plain-language question
you can't reduce to terms of art. Keep `hybrid_balance=0` when you need every result to contain your words.

### 3.6 Which fields are searched (`fieldset`)

- `titlebody`: the section's name and text. Default for `or`, `and`, `phrase`.
- `ranktext`: also the section number, the headings above it, and its history notes. Default for the Boolean types
  and for `hybrid_balance` above 0.

With `ranktext`, a heading word matches every section under that heading, and `NOT` excludes on headings too:
`privacy and not consumer` drops every section under a heading that says "consumer". Send `fieldset=titlebody` so
words match only the section's own name and text.

### 3.7 Restricting to a title or chapter (`within_division_path`)

If you know where the topic lives, restrict the search to that part of the tree. Tax: `FED-USC` title 26. Food and
drug labeling: `FED-CFR` title 21. This is the biggest single relevance gain available.

- Requires the law-scoped route `/jurisdictions/:jurisdiction_key/laws/:law_key/search`. On the jurisdiction-wide
  route it returns `400`.
- Takes up to 100 comma-separated paths. A path covers its whole subtree, matched by whole label: `title_1` includes
  `title_1.chapter_2` but not `title_10`.

### 3.8 Federal law alongside a state (`with_federal`)

`with_federal=true` on the jurisdiction-wide route (`/jurisdictions/:jurisdiction_key/laws/search`) adds federal law
to a state search. It runs two searches, one over the state's laws and one over all federal law, and takes results
from the two in turn, starting with the state. Each page lists its state results first, then its federal results, so
state and federal results don't alternate within a response.

- To combine a law-scoped search (`/laws/:law_key/search`) with federal law, run a second search under `FED`.
- Under `FED`, `with_federal` does nothing and the response carries `With-Federal: ignored`.
- **Citation lookup takes `with_federal` too:** a state lookup with `with_federal=true` also reads federal
  citations (§4).
- Federal `search_scores` come from the separate search; compare them only with each other.

### 3.9 Narrowing and broadening

| Problem | Try, roughly in order |
|---|---|
| Too many or noisy results | A quoted phrase · `type=and` · NOT · `within_division_path` · `fieldset=titlebody` · better terms of art |
| Too few or none | More synonyms (OR) · drop `within_division_path` · search the whole jurisdiction with `with_federal=true` · `hybrid_balance=auto` |

### 3.10 What search returns

- An **array of full Division objects** (same shape as a direct lookup), best match first.
- Each carries **`search_scores`**: `relevance`, plus `lexical` and `semantic` when `hybrid_balance` is above 0.
  Compare scores only within one response.
- **Pages:** `limit` 1–50 (default 10) and `offset` 0–200. The deepest page is `offset=200&limit=50`. An offset past
  the last result returns `404`. Each page is a new search, so results can shift between pages.
- **No match → `404`**, not an empty array.
- **`Search-Coverage: partial`** means the search stopped before covering every section, usually on time. A better
  match may be missing. Retry, or narrow with a law key.
- **There is no effective-date filter.** Filter `effective_date_*` yourself after retrieval.

---

## 4. Citation lookup

```
GET /api/v1/jurisdictions/:jurisdiction_key/laws/citations?query=<citation>
```

**Send each citation under the jurisdiction it names.** A U.S. Code or C.F.R. citation goes to `FED`. When the
citations in a state matter mix state and federal law (a California brief citing both `Cal. Gov't Code § 12940` and
`42 U.S.C. § 1983`), add `with_federal=true` to the state lookup and it reads both. Without `with_federal`, a federal
citation sent under `CA` returns `400`.

**Send the citation itself, in Bluebook form.** Strip everything around it before the lookup:

- **No signals or act names in front:** send `29 U.S.C. § 207`, not `See 29 U.S.C. § 207` or
  `Fair Labor Standards Act, 29 U.S.C. § 207`.
- **No edition or year parentheticals:** send `N.Y. C.P.L.R. 3211`, not `N.Y. C.P.L.R. 3211 (McKinney 2026)`. The
  lookup returns today's text whatever year the citation names.
- **A hyphen inside a section number:** `42 U.S.C. § 300i-4`.
- **A range: `§§` and an en dash:** `Fla. Stat. §§ 682.01–682.25`. A range returns its first section. After a single
  `§`, an unspaced en dash can mean one hyphenated section or a range. When only one reading parses, the lookup uses
  it. When both parse, it answers `409` with the two citations to choose from. When neither parses, it answers `400`
  with a hint.
- **A chapter citation returns the chapter:** `Mass. Gen. Laws ch. 93A` returns the chapter Division, which has
  children and no text of its own.

**Also accepted.** Citations copied from documents often carry extra text, and the parser recovers from most of it:
missing periods (`42 USC § 1983`), a final period, signals and act names, edition parentheticals, trailing
`et seq.` or `note`, split pincites (`§ 473, (d)`), and subdivision words (`subd. 5`). Recovery costs extra parsing
attempts and can drop meaning (a parenthetical such as `(repealed)` is discarded), so clean the citation when you
can.

**Local citation forms** are a state's own citation style instead of the Bluebook's: RCW, ORS, NRS, K.S.A., M.C.L.,
HRS, N.J.S.A., O.C.G.A. Lookup of local forms is part of the Enterprise Law Data API plan (§5). Bluebook citations
work on both plans.

URL-encode the citation: many contain `&` (`Cal. Bus. & Prof. Code`).

| Response | Meaning | Next step |
|---|---|---|
| `200` | One Division | Use it; check `is_repealed` |
| `400` `Invalid citation format` | Doesn't parse as any citation form for this jurisdiction | Check the jurisdiction; if `detail` gives a corrected citation, send it; otherwise rewrite in Bluebook form and retry once |
| `404` | Parses, but no Division matches | The provision may be repealed, renumbered, not stored, or nonexistent. Search for its subject instead |
| `409` `Ambiguous citation` | Several Divisions match (for example a U.S. Code part letter that repeats across chapters) | Send one of the citations `detail` lists |

A Bluebook citation addresses down to the section. Pincites in the query are accepted, but the lookup returns the
section; use `markdown_content` pincite markers (§11) to find the subdivision.

---

## 5. Authentication, access, and plans

```
Authorization: Bearer <your-token>
```

- The token is an opaque 32-character string. Treat it as a secret: environment variable or secrets manager, never
  source control or client-side code.
- Send it on every call. Missing or invalid → `401`.

**Getting a token.** Request access through the Get API Access form on https://openlaws.us/pricing. Evaluation keys
are free; OpenLaws issues one after a meeting about your use case.

**Plans** (details on the pricing page):

| Plan | For | Adds |
|---|---|---|
| Law Data API | Teams building with legal data in production | — (everything in this guide not listed below) |
| Enterprise Law Data API | Teams that need security review, procurement support, and an SLA | `current_as_of` on each Division: the date OpenLaws last checked this law against its source. `html_content` where the plan includes rendered HTML. Local citation forms (§4). An SLA and same-business-day support |

Search modes, including hybrid, are available on both plans.

---

## 6. Endpoint reference

Relative to `https://api.openlaws.us`; all require the bearer header.

### Discovery

| Method and path | Returns |
|---|---|
| `GET /api/v1/jurisdictions/:jurisdiction_key/laws` | Laws in one jurisdiction. **Use this to discover law keys.** |
| `GET /api/v1/laws` | Every law across all jurisdictions. |
| `GET /api/v1/jurisdictions` | All jurisdictions, each with its laws. |

Jurisdiction and law lists change rarely; cache them.

### Retrieval

| Method and path | Returns |
|---|---|
| `GET /api/v1/jurisdictions/:jurisdiction_key/laws/citations?query=…` | The Division a citation names (§4). Add `with_federal=true` to read federal citations under a state. |
| `GET /api/v1/jurisdictions/:jurisdiction_key/laws/:law_key/divisions` | The law's root Divisions. Start tree walks here. `404` if the law has none. |
| `GET /api/v1/jurisdictions/:jurisdiction_key/laws/:law_key/divisions/<path>` | One Division by path. |

### Search

| Method and path | Scope |
|---|---|
| `GET /api/v1/jurisdictions/:jurisdiction_key/laws/search` | All laws in the jurisdiction. |
| `GET /api/v1/jurisdictions/:jurisdiction_key/laws/:law_key/search` | One law. Required for `within_division_path`. |

Parameters: `query` (required) · `type` · `hybrid_balance` · `fieldset` · `with_federal` (jurisdiction-wide route) ·
`within_division_path` (law-scoped route) · `limit` · `offset`. See §3.

---

## 7. Response shapes

### Division

A real response for `42 U.S.C. § 1983`, trimmed:

```jsonc
{
  "jurisdiction_key": "FED",
  "law_key": "FED-USC",
  "path": "title_42.chapter_21.subchapter_i.section_1983",
  "label": "section_1983",
  "division_type": "section",
  "identifier": "1983",                  // not unique; leading zeros preserved ("010")
  "range_end_identifier": null,          // set for ranges, e.g. §§ 1981–1983
  "name": "Civil action for deprivation of rights",
  "display_name": "Section 1983: Civil action for deprivation of rights",
  "openlaws_web_url": "https://static.openlaws.us/laws/fed/usc/title_42/chapter_21/subchapter_i/section_1983",
  "effective_date_start": "1996-10-19",
  "effective_date_end": "Infinity",      // no end date recorded (see field notes)
  "aliases": null,                       // string array or null
  "plaintext_content": "Every person who, under color of any statute, ...",
  "markdown_content": "Every person who, under color of any statute, ...",
  "annotations": "...",
  "is_repealed": false,                  // true · false · null (unknown)
  "is_reserved": false,
  "renumbered": null,
  "display_ancestors": [
    { "display_name": "Title 42: The Public Health and Welfare", "path": "title_42" },
    { "display_name": "Chapter 21: CIVIL RIGHTS", "path": "title_42.chapter_21" },
    { "display_name": "Subchapter I: GENERALLY", "path": "title_42.chapter_21.subchapter_i" }
  ],
  "display_children": [],
  "updated_at": "2026-11-03",
  "search_scores": { "relevance": 12.3456 }   // search results only
}
```

Field notes:

- **`display_name`:** use it for labels. It handles missing types, numbers, and names: California's
  `Cal. Gov't Code § 12940` has `"display_name": "Section 12940"` because the source gives no section name.
- **`plaintext_content`** is clean text for models. **`markdown_content`** adds structure and pincite markers (§11).
  It is `null` where OpenLaws holds only plain text, such as laws published as scanned documents; use
  `plaintext_content` then. **`html_content`** appears on Enterprise Law Data API tokens that include rendered HTML,
  and falls back to escaped plaintext when there's no markdown.
- **`annotations`:** the rest of the source page: history notes, agency and attorney-general interpretations. Often
  better grounding than a web search.
- **`is_repealed`, `is_reserved`:** `true`/`false` only when the source says so; `null` means unknown. If a provision
  disappears from the source, it disappears from OpenLaws; no repeal is inferred.
- **`effective_date_start`, `effective_date_end`:** a date (`YYYY-MM-DD`), or one of two strings when no date is
  recorded on that side:
  - `effective_date_end: "Infinity"`: no end date is recorded.
  - `effective_date_start: "-Infinity"`: no start date is recorded.

  Both strings together mean the effective dates are unknown. Neither string shows that a provision is in force: a
  version with no end date may take effect in the future, so check the start date and `is_repealed` too. Parse both
  strings before comparing dates. The dates are best effort, and they are not a search filter.
- **`display_ancestors`, `display_children`:** tree navigation, and context for a model.
- **`openlaws_web_url`:** a stable hosted view. Use it so users can verify your answer, and as the easiest rendered
  view (§11).

**Versions.** Codified law is edited in place. The true unique key is (`law_key`, `path`, effective-date range): one
path can have past, current, and future-effective versions. Use the current one, and don't assume one path is one
document forever.

### Law

```jsonc
{ "key": "CA-RR", "jurisdiction_key": "CA", "law_type": "regulations", "name": "California Code of Regulations", "aliases": null }
```

### Errors (RFC 9457 problem details)

```jsonc
{ "status": 400, "title": "Invalid citation format", "detail": "…" }
```

`title` names the problem. `detail`, when present, says how to fix it, often with a corrected query or citation.

---

## 8. Errors and recovery

| Status | Meaning | Next step |
|---|---|---|
| `400` | Malformed input: unparseable citation or Boolean query, bad parameter | Read `title` and `detail`; send the correction `detail` gives, or fix the parameter |
| `401` | Token missing or invalid | Stop and report |
| `404` | Well-formed, no match | Search: broaden (§3.9). Citation: search for the subject (§4). After several good attempts, report "no provision found" |
| `409` | Ambiguous citation | Send one of the citations in `detail` |
| `429` | Rate limited | Wait `Retry-After` seconds, then retry |
| `503` | Search backend unavailable | Retry with backoff |
| `200` or `404` + `Search-Coverage: partial` | Search stopped before covering every section, usually on time | Retry, or narrow with a law key |

`400` and `404` mean different things: `400` = fix the input; `404` = the input was fine and nothing matched.

---

## 9. Rate limits, caching, and storage

- **Rate limits prevent abuse of OpenLaws' intellectual property,** such as copying the corpus or portions of it
  through the API. Research use is unmetered: run parallel searches freely, but don't crawl.
- **Burst limit per token:** 100 requests per 5 seconds. Sustained limits also apply. There are no quota headers.
- **On `429`, wait the number of seconds in `Retry-After`, then retry.** Retrying sooner gets another `429`. The
  response's `detail` names the limit you hit.
- **Responses can be large.** One Division can hold a long text: 21 C.F.R. § 101.9 (nutrition labeling) has about
  135,000 characters of plaintext, returned again as markdown. A search returns up to `limit` full Divisions. Keep
  `limit` small, and pass a model only the text it needs.
- **Caching:** you may cache responses for 24–48 hours, as strictly necessary to enhance the performance of your
  application. Don't copy the corpus or portions of the corpus to local storage or databases; for a local copy, see
  bulk data below.
- **Bulk data.** Integrators who need large amounts of data use bulk data, delivered to an AWS S3 bucket, instead of
  the API. It also serves strict data-security requirements, embedding the corpus, and comparing historical
  versions. Ask through the pricing page.

---

## 10. Coverage

- **53 jurisdictions:** the 50 states, DC, Puerto Rico, and federal, about 4.7 million documents in all. Coverage is
  never 100%: some sources are messy (inconsistent PDFs, sources offline).
- **Federal:** U.S. Code (`FED-USC`, including the federal court rules in its appendices), CFR (`FED-CFR`),
  Constitution (`FED-CONST`), executive orders.
- **States:** statutes, regulations, constitutions, and codified court rules; the mix varies by state.
- **Freshness:** federal weekly; the highest-traffic states monthly; the rest quarterly. Enterprise tokens get
  `current_as_of` on each Division.
- **Discover programmatically:** `GET /api/v1/jurisdictions/:jurisdiction_key/laws`. Never assume a law key exists.

**Not here:** case law and court opinions, agency guidance and enforcement letters, bills and session laws, and court
rules that exist only as court-issued rules. When unsure whether something is covered, ask in the OpenLaws Slack
channel; the team knows each jurisdiction's quirks.

---

## 11. Reading OpenLaws markdown

`markdown_content` is CommonMark plus GitHub-Flavored Markdown, with two OpenLaws extensions:

- **Pincite shortcodes** mark each subdivision, so you can chunk down to one subsection:

  ```
  {{< pincite identifier="a_4" display="a" >}}
  ```

  `identifier` is the address; `display` is what's shown.

- **List attribute classes** set statutory numbering styles: `{ .parens-decimal }` → `(1)`,
  `{ .parens-lower-alpha }` → `(a)`.

Numbering has edge cases (lists past `Z` continue `AA, BB, CC`; duplicates occur). The `display` value is
authoritative; don't compute numbering yourself.

Rendering this to HTML faithfully is hard. Easiest first: use `plaintext_content` if you only need text; link
`openlaws_web_url` for a rendered view; or use `html_content` on an Enterprise Law Data API token that includes
rendered HTML.

---

## 12. Data is messy

OpenLaws models the source faithfully. Assumptions that will bite you:

- **Identifiers are not unique.** A jurisdiction can have two "Chapter 5"s. Key on `path` (plus effective date).
- **Formatting is preserved:** `010`, not `10`, because that's how the citation reads.
- **Source errors are preserved:** a source typo stays in the text.
- **Paths can move.** States recodify and agencies reorganize. Don't treat `path` as permanent.
- **Expect gaps and future-effective versions.** Don't enforce referential integrity across the corpus.

---

## 13. Worked recipes

### A. "I have a citation; get me the text"

```bash
curl -sG https://api.openlaws.us/api/v1/jurisdictions/CA/laws/citations \
  -H "Authorization: Bearer $OPENLAWS_TOKEN" \
  --data-urlencode "query=Cal. Gov't Code § 12940"
```

`400`: check the jurisdiction and apply `detail`. `404`: search for the subject. `409`: pick from `detail`.

### B. "Find provisions on a topic, with synonym groups"

```bash
curl -sG https://api.openlaws.us/api/v1/jurisdictions/CA/laws/search \
  -H "Authorization: Bearer $OPENLAWS_TOKEN" \
  --data-urlencode "type=terms_and_connectors" \
  --data-urlencode "query=(\"meal break\" or \"meal period\") and employee" \
  --data-urlencode "with_federal=true" \
  --data-urlencode "limit=20"
```

Run a few variants like this in parallel; merge and re-rank.

### C. "Restrict to a known title"

```bash
# Tax question: search only Title 26 of the U.S. Code.
curl -sG https://api.openlaws.us/api/v1/jurisdictions/FED/laws/FED-USC/search \
  -H "Authorization: Bearer $OPENLAWS_TOKEN" \
  --data-urlencode "query=qualified business income deduction" \
  --data-urlencode "within_division_path=title_26"
```

### D. "Keyword searches missed; fall back to hybrid"

```bash
curl -sG https://api.openlaws.us/api/v1/jurisdictions/CA/laws/search \
  -H "Authorization: Bearer $OPENLAWS_TOKEN" \
  --data-urlencode "hybrid_balance=auto" \
  --data-urlencode "query=can a landlord keep a security deposit for normal wear and tear"
```

### E. "Walk a law's structure"

```bash
curl -s https://api.openlaws.us/api/v1/jurisdictions/FED/laws/FED-CFR/divisions \
  -H "Authorization: Bearer $OPENLAWS_TOKEN"            # roots
curl -s https://api.openlaws.us/api/v1/jurisdictions/FED/laws/FED-CFR/divisions/title_21/chapter_i \
  -H "Authorization: Bearer $OPENLAWS_TOKEN"            # a path from display_children
```

---

## 14. Worked example: a hard query, end to end

Question: *"Is a lowest-price advertising claim for an RV allowed in Texas?"* Here is the path a law librarian would
take, mapped to API calls.

1. **Is this codified law?** Advertising and pricing rules are codified in statutes and regulations. A court ruling
   or an agency enforcement letter would be out of scope.
2. **Jurisdiction.** Texas, and advertising claims are often federal (the FTC). Plan `TX` and `FED` searches.
3. **Type of law.** Both. A consumer-protection statute typically bans deceptive advertising in general terms, and
   regulations add the specifics for a product or industry. Search `TX-STAT` and `TX-RR`, then `FED-CFR`.
4. **Synonym expansion, specific to broad,** one terms-and-connectors query per level. There is no wildcard, so
   write the forms out:
   `("recreational vehicle" or "travel trailer" or "motor home") and (advertising or advertisement) and price`.
   Then broaden: drop `price`, then drop the vehicle terms. "RV" is genuinely hard: the law treats one as both a
   vehicle and a dwelling. As the terms broaden, discard motorcycle and registration hits more strictly.
5. **Restrict where you can.** Price advertising is consumer protection and trade practices, not vehicle
   registration. Once a hit shows the right title in `display_ancestors`, search within it with
   `within_division_path`.
6. **Fallback.** If the expanded searches miss, run the question with `hybrid_balance=auto`.
7. **Read the hits properly.** Find the definitions section for the chapter (does "vehicle" include an RV?), follow
   cross-references, and check `is_repealed` and effective dates.
8. **Watch preemption.** A state rule may be preempted by federal law.
9. **A persistent `404` is a finding.** If good variants find nothing, report that no specific provision was found;
   don't invent a citation.

---

## 15. Checklist

- [ ] Scope every search and lookup to a jurisdiction, in the URL. No state names in `query`.
- [ ] Send federal citations under `FED`, or add `with_federal=true` to a state citation lookup.
- [ ] Send the bare citation: no signals or edition parentheticals; `§§` and an en dash for ranges.
- [ ] Statute ≠ regulation. Operational rules are usually regulations; check both.
- [ ] Prefer citation, then path, then search.
- [ ] Synonym expansion with terms of art; write out irregular forms and spelling variants.
- [ ] Use `terms_and_connectors` for synonym groups; read the `400` `detail` when a query is rejected.
- [ ] Restrict with `within_division_path` when you know the title (law-scoped route).
- [ ] Fall back to `hybrid_balance=auto` when expanded keyword searches miss.
- [ ] Read results in context: definitions, cross-references, `display_ancestors`.
- [ ] Check `is_repealed` (`null` = unknown) and effective dates.
- [ ] `400` = fix the input; `404` = no match; `409` = pick a citation from `detail`.
- [ ] Use `display_name` for labels.
- [ ] Ground answers: quote text, give the citation and `openlaws_web_url`; never cite from memory.
- [ ] Keep client facts out of queries.
- [ ] Cache 24–48 hours, only as needed for performance; don't copy the corpus or portions of it to local storage
  or databases.
- [ ] Honor `Retry-After` on `429`.

Questions about a jurisdiction's quirks: ask in the OpenLaws Slack channel. Enterprise Law Data API plans include an
SLA.
