> ## Documentation Index
> Fetch the complete documentation index at: https://vaquill.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get one subsection

> Resolve a citation that carries a subsection, such as 625 ILCS 5/11-601(c), and get exactly that unit's text back: how to read it, how to handle a miss, and the same lookup from a body, a document or a search

**What this gets you:** exactly the text of the subsection a citation names, with no second model call and no parsing on your side.
You also get the sentence it completes, the units inside it and beside it, and a grade that says how far to trust the outline.

A citation such as `625 ILCS 5/11-601(c)` names one subsection of a section that can run to dozens.
Send it to `/us/statutes/resolve` and the response carries the whole section as before, plus a `pinpoint` object holding unit (c) itself.
This recipe shows the call, how to read the result, what a miss looks like, and the three other routes that return the same object.

**Endpoints used:** `GET` and `POST /us/statutes/resolve`, `POST /us/statutes/extract-citations`, `GET /us/statutes/section/{actId}/body`, `POST /us/statutes/search`.

> [!NOTE]
>
> The concept page, [Pinpoints](https://vaquill.ai/docs/api-guide/concepts/pinpoints.md), has the full field reference, the citation forms that are read, the error table and coverage by state.
> This page is the working example.

## Resolve a citation with a pinpoint

Put the pinpoint in the citation, exactly as a court or a statute book prints it.
A resolve with a pinpoint costs the resolve price, 2 credits per citation.

```bash cURL theme={"theme":"github-light"}
curl -G https://api.vaquill.ai/api/v1/us/statutes/resolve \
  -H "Authorization: Bearer vq_key_..." \
  --data-urlencode "cite=625 ILCS 5/11-601(c)" \
  --data-urlencode "state=il"
```

```python Python theme={"theme":"github-light"}
import requests

resp = requests.get(
    "https://api.vaquill.ai/api/v1/us/statutes/resolve",
    headers={"Authorization": "Bearer vq_key_..."},
    params={"cite": "625 ILCS 5/11-601(c)", "state": "il"},
)
resp.raise_for_status()
data = resp.json()

if not data["resolved"]:
    print("Unverified citation:", data["inputCitation"])
elif "pinpoint" in data:
    pin = data["pinpoint"]
    print(pin["matched"], pin["matchLevel"], pin["structure"]["quality"])
    print(pin["text"])
else:
    # The section resolved but the unit could not be looked up this time.
    print(data.get("pinpointNote"))
```

```javascript JavaScript theme={"theme":"github-light"}
const url = new URL("https://api.vaquill.ai/api/v1/us/statutes/resolve");
url.searchParams.set("cite", "625 ILCS 5/11-601(c)");
url.searchParams.set("state", "il");

const resp = await fetch(url, {
  headers: { Authorization: "Bearer vq_key_..." },
});
if (!resp.ok) throw new Error(`resolve failed: ${resp.status}`);
const data = await resp.json();

if (!data.resolved) {
  console.warn("Unverified citation:", data.inputCitation);
} else if (data.pinpoint) {
  const pin = data.pinpoint;
  console.log(pin.matched, pin.matchLevel, pin.structure.quality);
  console.log(pin.text);
} else {
  // The section resolved but the unit could not be looked up this time.
  console.log(data.pinpointNote);
}
```

A trimmed response (the `section` object is cut to two fields):

```json theme={"theme":"github-light"}
{
  "resolved": true,
  "inputCitation": "625 ILCS 5/11-601(c)",
  "section": { "actId": "STATE_IL_C625_A5_S11-601", "citation": "625 ILCS 5/11-601" },
  "subsection": "c",
  "pinpoint": {
    "requested": "(c)",
    "path": ["c"],
    "label": "(c)",
    "level": "subsection",
    "matched": true,
    "matchLevel": "exact",
    "text": "Unless some other speed restriction is established under this Chapter, the maximum speed limit in an urban district for all vehicles is:",
    "leadIn": [],
    "fullText": "(c) Unless some other speed restriction is established under this Chapter, the maximum speed limit in an urban district for all vehicles is: 1. 30 miles per hour; and 2. 15 miles per hour in an alley.",
    "children": [
      { "path": ["c", "1"], "label": "1.", "level": "paragraph", "text": "30 miles per hour; and" },
      { "path": ["c", "2"], "label": "2.", "level": "paragraph", "text": "15 miles per hour in an alley." }
    ],
    "siblings": { "previous": "b", "next": "d" },
    "charStart": 1493,
    "charEnd": 1693,
    "structure": {
      "source": "request_time",
      "quality": "verified",
      "builder": "text-grammar/1:il",
      "textSha256": "dfbee96a02574de186178e776364f8557f6e2ed760a31ae5df7232d1f27104b0"
    }
  },
  "creditsConsumed": 2.0
}
```

`subsection` still echoes the dot-joined pinpoint (`c`).
Read `pinpoint.path` when you need the unit itself.

## Read the result

Five fields decide what you do with the answer.

| Field | What it tells you |
| - | - |
| `matched` | `true` when the unit you asked for exists. Check this first, on every call |
| `matchLevel` | `exact`, `ancestor` or `none`. On `ancestor` the block describes a unit above the one you asked for |
| `structure.quality` | `native`, `verified`, `heuristic` or `none`. How far to trust the outline |
| `children` | The units inside this one, each with its own `path`, `label`, `level` and `text` |
| `siblings` | The labels of the previous and next unit at the same level, `null` at either end |

Some units are a few words that finish a sentence started above them.
`leadIn` carries those parent sentences, outermost first, so you can quote the unit in context.
Here is `Mo. Rev. Stat. 565.021.1(1)`, the first paragraph of the Missouri offense of murder in the second degree:

```json theme={"theme":"github-light"}
{
  "requested": "(1)(1)",
  "path": ["1", "1"],
  "label": "(1)",
  "level": "paragraph",
  "matched": true,
  "matchLevel": "exact",
  "text": "Knowingly causes the death of another person or, with the purpose of causing serious physical injury to another person, causes the death of another person; or",
  "leadIn": [
    {
      "path": ["1"],
      "label": "1.",
      "text": "A person commits the offense of murder in the second degree if he or she:"
    }
  ],
  "fullText": "(1) Knowingly causes the death of another person or, with the purpose of causing serious physical injury to another person, causes the death of another person; or",
  "children": [],
  "siblings": { "previous": null, "next": "2" },
  "charStart": 120,
  "charEnd": 282,
  "structure": {
    "source": "request_time",
    "quality": "verified",
    "builder": "text-grammar/1:mo",
    "textSha256": "69fc6122328912da85501e29313e3fc00c2baec59ea5d655009372c11a4b2a3a"
  }
}
```

The unit's own `text` is a fragment.
To quote it in full, join the `leadIn` text and the unit's `text`.

Here is what three of the other citations returned.
Each one was an exact match.

| Citation | `path` | `structure.quality` | `structure.source` |
| - | - | - | - |
| `Wis. Stat. 940.01(1)(a)` | `["1", "a"]` | `verified` | `request_time` |
| `Iowa Code 422.5(1)(b)` | `["1", "b"]` | `verified` | `request_time` |
| `Minn. Stat. 609.02 subd. 2` | `["2"]` | `native` | `artifact` |

The Wisconsin unit has `leadIn` text `Offenses.`, which is the heading of subsection (1).
The Iowa unit (b) opens with two numbered paragraphs, so its own `text` is empty and the content is in its two `children`.
When `text` is empty and `children` is not, read the children.
The Minnesota unit is a whole subdivision, `Subd. 2.` with the heading `Felony.`

`structure.source` says where the outline came from.
`artifact` means a pre-built outline of this section was used, and `request_time` means the outline was parsed from the section text on this call.
Neither is a grade.
`structure.quality` is the grade, so treat a `heuristic` unit as a pointer to confirm against the text and a `none` as "unknown", never as "this section has no subsections".

## Handle a miss

A pinpoint can name a unit the section does not have.
The call still succeeds and is charged, because the section resolved.
The block says what happened instead of returning the whole section.

`Minn. Stat. 609.02 subd. 2(1)` asks for paragraph (1) inside subdivision 2, which has none.
This is the `pinpoint` object of that item from `POST /us/statutes/resolve`:

```json theme={"theme":"github-light"}
{
  "requested": "(2)(1)",
  "path": ["2"],
  "label": "Subd. 2.",
  "level": "subdivision",
  "matched": false,
  "matchLevel": "ancestor",
  "text": "Felony.\n\n\"Felony\" means a crime for which a sentence of imprisonment for one year or more may be imposed.",
  "leadIn": [],
  "fullText": "Subd. 2.Felony.\n\n\"Felony\" means a crime for which a sentence of imprisonment for one year or more may be imposed.",
  "children": [],
  "siblings": { "previous": "1", "next": "2a" },
  "charStart": 179,
  "charEnd": 292,
  "unmatched": ["1"],
  "reason": "no_such_subsection",
  "note": "This section has no (2)(1). The text returned is (2), the deepest unit that exists; (1) was not found.",
  "structure": {
    "source": "artifact",
    "quality": "native",
    "builder": "mn-native-1",
    "textSha256": "e8329c88c5f2a40182e61c63ac6e02f516eacb95e4ab55a183c97e632294a2b8"
  }
}
```

Note that `matched` is `false` while the `text` is real text.
It is the deepest unit that exists (`path` is `["2"]`), not the one you asked for.
Never present it as the answer to `(2)(1)`.

```python Python theme={"theme":"github-light"}
pin = data["pinpoint"]
if pin["matched"]:
    use(pin["text"], pin["leadIn"])
elif pin["matchLevel"] == "ancestor":
    # The section has a unit above the one requested. Show it as context
    # and tell the reader which part was not found.
    print("Not found:", pin["unmatched"], "-", pin["note"])
    print("Closest unit:", pin["label"])
elif pin["reason"] == "no_structure":
    # We could not recover this section's outline. The text is still at /body.
    fetch_full_body(data["section"]["actId"])
else:
    print("No such subsection. Labels that exist:", pin.get("available"))
```

```javascript JavaScript theme={"theme":"github-light"}
const pin = data.pinpoint;
if (pin.matched) {
  use(pin.text, pin.leadIn);
} else if (pin.matchLevel === "ancestor") {
  // The section has a unit above the one requested. Show it as context
  // and tell the reader which part was not found.
  console.warn("Not found:", pin.unmatched, "-", pin.note);
  console.log("Closest unit:", pin.label);
} else if (pin.reason === "no_structure") {
  // We could not recover this section's outline. The text is still at /body.
  await fetchFullBody(data.section.actId);
} else {
  console.warn("No such subsection. Labels that exist:", pin.available);
}
```

The reasons:

* `no_such_subsection`: the outline is known and has no such unit.
  `available`, when present, lists the labels that do exist where the lookup stopped, so a mistyped pinpoint can be corrected without another call.
* `no_structure`: we could not recover the section's outline.
  The section text is still available at `/body`.

If the response has `pinpointNote` and no `pinpoint`, the unit could not be looked up this time.
The section resolved and is charged as usual, and a retry usually answers.

## Pinpoints in a document

`POST /us/statutes/extract-citations` finds every citation in a block of text and, with `resolve: true`, resolves each one.
It is priced per distinct citation.
The two citations below cost 4 credits.

```bash theme={"theme":"github-light"}
curl -X POST https://api.vaquill.ai/api/v1/us/statutes/extract-citations \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The speed limit in an urban district is set by 625 ILCS 5/11-601(c). Intentional homicide is covered by Wis. Stat. 940.01(1)(a).",
    "resolve": true
  }'
```

A trimmed response, keeping the fields used here:

```json theme={"theme":"github-light"}
{
  "citations": [
    {
      "citation": "Wis. Stat. 940.01",
      "raw": "Wis. Stat. 940.01(1)(a)",
      "pinpoint": "(1)(a)",
      "resolved": true,
      "actId": "STATE_WI_C940_S940.01"
    },
    {
      "citation": "625 ILCS 5/11-601",
      "raw": "625 ILCS 5/11-601(c)",
      "pinpoint": "(c)",
      "resolved": true,
      "actId": "STATE_IL_C625_A5_S11-601"
    }
  ],
  "counts": { "found": 2, "resolved": 2, "unresolved": 0, "skipped": 0 },
  "creditsConsumed": 4.0
}
```

Each row keeps the pinpoint exactly as it was printed in your text (`pinpoint`) and the full citation as printed (`raw`).
A row also carries `pinpointMatch`, the same block as `pinpoint` above, when the unit could be located in the same call.
Read `pinpointMatch.matched` first, as you would on a resolve.

When a row has no `pinpointMatch`, resolve its `raw` to get the unit.
That is one more resolve call at the resolve price, and you can batch up to 50 of them:

```bash theme={"theme":"github-light"}
curl -X POST https://api.vaquill.ai/api/v1/us/statutes/resolve \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{"citations": ["Wis. Stat. 940.01(1)(a)", "625 ILCS 5/11-601(c)"]}'
```

## Pinpoints from an act ID you already hold

If you already have an `actId`, ask the body route for the unit.
You get the full section body and the unit side by side.
A body with a pinpoint is the body price, 6 credits.

```bash theme={"theme":"github-light"}
curl -G https://api.vaquill.ai/api/v1/us/statutes/section/STATE_IL_C625_A5_S11-601/body \
  -H "Authorization: Bearer vq_key_..." \
  --data-urlencode "pinpoint=(c)(1)"
```

A trimmed response (`html` and `plain` carry the whole section and are cut here):

```json theme={"theme":"github-light"}
{
  "actId": "STATE_IL_C625_A5_S11-601",
  "plain": "(625 ILCS 5/11-601) (from Ch. 95 1/2, par. 11-601) Sec. 11-601. General speed restrictions. ...",
  "sourceUrl": "https://www.ilga.gov/legislation/ilcs/documents/062500050K11-601.htm",
  "available": true,
  "pinpoint": {
    "requested": "(c)(1)",
    "path": ["c", "1"],
    "label": "1.",
    "level": "paragraph",
    "matched": true,
    "matchLevel": "exact",
    "text": "30 miles per hour; and",
    "leadIn": [
      {
        "path": ["c"],
        "label": "(c)",
        "text": "Unless some other speed restriction is established under this Chapter, the maximum speed limit in an urban district for all vehicles is:"
      }
    ],
    "fullText": "1. 30 miles per hour; and",
    "children": [],
    "siblings": { "previous": null, "next": "2" },
    "charStart": 1634,
    "charEnd": 1659,
    "structure": {
      "source": "request_time",
      "quality": "verified",
      "builder": "text-grammar/1:il",
      "textSha256": "dfbee96a02574de186178e776364f8557f6e2ed760a31ae5df7232d1f27104b0"
    }
  },
  "creditsConsumed": 6.0
}
```

`charStart` and `charEnd` index into the `plain` text of this same response.
Here `plain[1634:1659]` is `1. 30 miles per hour; and`, the unit's `fullText`.
`structure.textSha256` is the SHA-256 of that `plain`, so you can check that a copy of the text you stored still matches the offsets:

```python theme={"theme":"github-light"}
import hashlib

if hashlib.sha256(plain.encode("utf-8")).hexdigest() != pin["structure"]["textSha256"]:
    # The section text changed since you stored it. Fetch the body again
    # and use the new offsets.
    refresh()
```

A malformed `pinpoint`, or a `pinpoint` sent together with `asOf`, is a `422` and is not charged.

## Which subsection did a search hit match

Search ranks whole sections.
Set `includePinpoint: true` and each hit also names the subsection it matched, in a `pinpoints` object keyed by `actId`.
It adds nothing to the price of the search.

```bash theme={"theme":"github-light"}
curl -X POST https://api.vaquill.ai/api/v1/us/statutes/search \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "30 mph urban district speed limit", "state": "il", "includePinpoint": true, "limit": 2}'
```

The first of the two hits, trimmed to the `pinpoints` entry that goes with it:

```json theme={"theme":"github-light"}
{
  "results": [
    { "actId": "STATE_IL_C625_A5_S11-601", "citation": "625 ILCS 5/11-601" }
  ],
  "pinpoints": {
    "STATE_IL_C625_A5_S11-601": {
      "located": true,
      "path": ["c", "1"],
      "label": "1.",
      "level": "paragraph",
      "pinpoint": "(c)(1)",
      "citation": "625 ILCS 5/11-601(c)(1)",
      "text": "30 miles per hour; and",
      "leadIn": [
        {
          "path": ["c"],
          "label": "(c)",
          "text": "Unless some other speed restriction is established under this Chapter, the maximum speed limit in an urban district for all vehicles is:"
        }
      ],
      "charStart": 1634,
      "charEnd": 1659,
      "matchedBy": "passage",
      "scope": "unit",
      "matchedTerms": ["30", "urban", "district", "speed", "limit"],
      "structure": {
        "source": "request_time",
        "quality": "verified",
        "builder": "text-grammar/1:il",
        "textSha256": "dfbee96a02574de186178e776364f8557f6e2ed760a31ae5df7232d1f27104b0"
      }
    }
  }
}
```

The `citation` is ready to paste back into `/us/statutes/resolve`.
`matchedBy: "passage"` means the unit lies inside the passage the search matched.
`scope: "unit"` means one unit matched best.
The second hit in the same response, `625 ILCS 5/11-604`, came back with `scope: "parent"`: several sub-units matched about equally, so the block names their common parent, `(b)`, instead of choosing between them.

A hit that cannot be named says why in `reason`.
That is a verdict about the hit and never changes which sections are returned, their order or their scores.

## Related

> **[Pinpoints](https://vaquill.ai/docs/api-guide/concepts/pinpoints.md)**
>
> Every field, the citation forms that are read, errors and coverage by state.

> **[Resolve and verify a statute citation](https://vaquill.ai/docs/api-guide/recipes/citation-lookup.md)**
>
> Resolve a citation to its section, one at a time or a document at a time.

> **[Citation formats](https://vaquill.ai/docs/api-guide/concepts/citation-formats.md)**
>
> Which citation strings resolve, and which are refused on purpose.

> **[Ground an LLM answer (RAG)](https://vaquill.ai/docs/api-guide/recipes/rag-grounding.md)**
>
> Feed the unit, not the whole section, to your model as its source.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.