Law change alerts

A board is a tracked source, identified by corpusType and state. Subscribe to one and we notify you by webhook or email when it changes. Every alert names the sections that changed. For an amended section you can fetch the old and new text. Start with GET /boards, then POST /watches. Every path below is prefixed with /api/v1 and every request needs an Authorization: Bearer vq_key_... header. Free routes still count against your rate limit.

Endpoint	Purpose	Credits
`GET /boards`	List the boards you can watch	Free
`GET /watches`	List your watches	Free
`POST /watches`	Create a watch	Free
`PATCH /watches/{watchId}`	Pause, resume or rotate a destination	Free
`DELETE /watches/{watchId}`	Remove a watch	Free
`POST /watches/{watchId}/test`	Fire a one-off test delivery	Free
`GET /watches/{watchId}/deliveries`	Webhook delivery history	Free
`GET /watches/{watchId}/changes`	The sections a board added, amended or removed	Free
`GET /watches/{watchId}/changes/{changeId}/diff`	The section’s text before and after one change. See Read the diff for one change	4

Only the diff is metered, because it rebuilds both sides of the text. Two plan limits apply to watches:

Plan	Webhook delivery	Watches
Business	Yes	Up to 100
Every other plan	No. A watch with `channel` set to `webhook` or `both` returns 403. Email works on every plan	Up to 3

Going over the watch cap returns 429. Delete a watch before creating another, or upgrade.

Boards and watches

GET /boards lists every board you can watch. Each has a corpusType, an optional state (omitted for federal boards), a label, and a refresh cadence. Compare lastRetrievedAt against cadence to see how recent a source is. For the cadence of each source, see Which statute cadence applies where. GET /boards lists only what can be watched, which is narrower than what we cover. For coverage, use GET /us/statutes/coverage. A watch is your subscription to one board, on a webhook, email, or both. By default it covers the whole board. To follow one title or part, see Narrow a watch to a citation. Two fields on each board show whether narrowing is available:

scopable: true when POST /watches accepts a scope for that source. It is false for sources such as the Federal Register, where an item is a numbered document with no title or part.
scopeBrowseCorpus: the corpusType to pass to GET /us/statutes/divisions to list the source’s titles, chapters and parts. Its spelling can differ from the board’s (a board is cfr, and /us/statutes/divisions wants CFR). When it is null, narrowing still works but no endpoint lists the hierarchy.

cURL

curl "https://api.vaquill.ai/api/v1/boards?limit=500&offset=0" \
  -H "Authorization: Bearer vq_key_..."

Python

import requests

def all_boards():
    """Page /boards. The default limit is also its maximum, so do not skip this."""
    boards, offset = [], 0
    while True:
        data = requests.get(
            "https://api.vaquill.ai/api/v1/boards",
            headers={"Authorization": "Bearer vq_key_..."},
            params={"limit": 500, "offset": offset},
        ).json()["data"]
        boards.extend(data["boards"])
        if not data.get("hasMore"):
            break
        offset += 500
    return boards

for b in all_boards():
    print(b["corpusType"], b.get("state"), b["label"], b["cadence"])

limit defaults to 500, which is also the maximum. If the list grows past 500, a call without offset returns the first 500 and no error. Read data.total and data.hasMore, and page on offset.

You can also filter with corpusType and state. Pass state=federal for boards with no state (USC, eCFR, the Federal Register). Omitting state is not the same.

{
  "data": {
    "boards": [
      {"corpusType": "state", "state": "wa", "label": "State statutes WA", "cadence": "monthly",
       "scopable": true, "scopeBrowseCorpus": "STATE"},
      {"corpusType": "federal_register", "label": "Federal Register", "cadence": "daily",
       "scopable": false, "scopeBrowseCorpus": null}
    ],
    "total": 312,
    "hasMore": false
  },
  "meta": { "processingTimeMs": 12.4, "creditsConsumed": 0 }
}

Create a watch

POST /watches with the board’s corpusType (and state, for a state board) plus a channel.

curl -X POST https://api.vaquill.ai/api/v1/watches \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "corpusType": "state",
    "state": "wa",
    "channel": "webhook",
    "webhookUrl": "https://example.com/hooks/vaquill",
    "webhookSecret": "a-secret-only-you-know"
  }'

import requests

resp = requests.post(
    "https://api.vaquill.ai/api/v1/watches",
    headers={
        "Authorization": "Bearer vq_key_...",
        "Content-Type": "application/json",
    },
    json={
        "corpusType": "state",
        "state": "wa",
        "channel": "webhook",
        "webhookUrl": "https://example.com/hooks/vaquill",
        "webhookSecret": "a-secret-only-you-know",
    },
)
watch = resp.json()["data"]

channel: webhook, email, or both. webhookUrl is required for webhook and both. emailAddress is required for email and both.
webhookSecret (optional): stored encrypted, never returned. When set, every delivery is HMAC-signed (see below).
webhookAuth (optional): a credential we send on every delivery, so your gateway can authenticate us. See Authenticating our deliveries.
webhookUrl must be a public address. Loopback, private, link-local and cloud metadata addresses are rejected.
corpusType: a value GET /boards returns. Send the board key (state_regulation) or the search-style token (REGULATION becomes state_regulation, USC becomes usc). Case does not matter. Any other value is a 422 that lists the allowed values. These cannot be watched: constitution, executive_action, agency_action, cfr_annual, usc_annual, federal_rules_annual, federal_rules_proposed, us_treaty, state_session_law, state_register and federal_bill.
404 if the corpusType and state pair does not match a board. 409 if you already have a watch on that board, channel and scope. Different scopes on the same board and channel are separate watches, so you can follow several parts at once.

GET /watches lists your watches. PATCH /watches/{watchId} pauses (isActive: false), resumes, or rotates a destination without losing history. DELETE /watches/{watchId} removes it.

Narrow a watch to a citation

A watch on a whole source reports every change. The federal regulations change daily, so to follow only 21 CFR part 314, set a scope:

curl -X POST https://api.vaquill.ai/api/v1/watches \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "corpusType": "cfr",
    "channel": "webhook",
    "webhookUrl": "https://example.com/hooks/vaquill",
    "scope": {"title": "21", "part": "314"}
  }'

resp = requests.post(
    "https://api.vaquill.ai/api/v1/watches",
    headers={
        "Authorization": "Bearer vq_key_...",
        "Content-Type": "application/json",
    },
    json={
        "corpusType": "cfr",
        "channel": "webhook",
        "webhookUrl": "https://example.com/hooks/vaquill",
        "scope": {"title": "21", "part": "314"},
    },
)

scope takes four optional keys, from broadest to narrowest: title, chapter, part, section. Omit scope to watch the whole source. Two rules apply, and both return a 400 if broken:

title is required when you set any narrower level.
section also needs chapter or part.

Values can be strings or numbers and are stored lowercased. "221.2" and "221_2" match the same section. Read scope from the response to see what we stored. A scoped watch stays silent when nothing in its scope changed. Deliveries carry a scope field, and changes holds only what is inside it. GET /watches/{watchId}/changes applies the same filter. Email subjects name the scope, for example eCFR (title 21, part 314) was updated. Sending a hierarchy scope to a source where scopable is false returns a 400 that lists the sources that accept one.

Or watch one exact section

Some sources have act_ids with no title, such as Missouri’s STATE_MO_C407_S407.822. A hierarchy scope cannot narrow these, because it requires title. Instead, name one section with the actId that search results and change events return:

{ "scope": { "actId": "CFR_T21_P314_S314_50" } }

It cannot be combined with the hierarchy keys. Sending both is a 400.
It is case-sensitive. Copy it verbatim (STATE_LA_Crevised-statutes_T14_S112.11).
It is checked when you create the watch. An act_id we do not hold, or one from a different source, is a 400.
It works on every source, including those where scopable is false. It is the only way to follow a single Federal Register document or one Justice Manual chapter.

A renumbered section gets a new act_id, so the watch stops matching. The watch fires once with a removed event for the old act_id.

Authenticating our deliveries

Two independent options are available. Set neither, either, or both.

	`webhookSecret`	`webhookAuth`
Answers	Is this body intact and from Vaquill?	Is this caller allowed in?
Sends	`X-Vaquill-Signature: sha256=<hex>`	`Authorization`, or a header you name
Checked by	Your handler, recomputing an HMAC	Your gateway, before your code runs

`scheme`	What arrives at your endpoint
`bearer`	`Authorization: Bearer <secret>`
`basic`	`Authorization: Basic <secret>` (encode `user:password` yourself)
`header`	`<headerName>: <secret>`, e.g. `X-Api-Key: <secret>`
`none`	No credential header. Sending this removes a stored one.

cURL

curl -X POST https://api.vaquill.ai/api/v1/watches \
  -H "Authorization: Bearer vq_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "corpusType": "state",
    "state": "wa",
    "channel": "webhook",
    "webhookUrl": "https://example.com/hooks/vaquill",
    "webhookAuth": {"scheme": "header", "headerName": "X-Api-Key", "secret": "k_live_..."}
  }'

The credential is stored encrypted and never returned. GET /watches shows only {"scheme": "...", "headerName": "...", "hasSecret": true}. Send webhookAuth as a whole object when you change it:

Change the credential: same scheme, new secret.
Rename the header, keep the token: same scheme, new headerName, and omit secret.
Change scheme: send secret again.
Turn it off: {"scheme": "none"}, which also deletes the stored credential.

headerName cannot be Authorization (use bearer or basic), a transport header, or an X-Vaquill-* header. These return a 400.

Receiving a webhook delivery

A delivery is a POST to your webhookUrl:

Headers:
  Content-Type: application/json
  X-Vaquill-Event: board.updated
  X-Vaquill-Signature: sha256=<hex>   (only when webhookSecret is set)

Body:
{
  "event": "board.updated",
  "corpusType": "cfr",
  "boardLabel": "Code of Federal Regulations",
  "rowsAdded": 4,
  "rowsUpdated": 2,
  "rowsDeleted": 0,
  "refreshLogId": 4412,
  "changes": [
    {"changeKind": "amended", "actId": "CFR_T21_P314_S314_50", "citation": "21 CFR 314.50", "title": "Content and format of an NDA"}
  ],
  "changesOverflowCount": 0,
  "deliveryId": "9f2b1e0a-...:4412",
  "firedAt": "2026-08-07T04:10:00Z"
}

changes holds at most 10 items. changesOverflowCount is the count beyond that. changeKind is added, amended, or removed. citation and title are null for some corpora, so fall back to actId. deliveryId is stable per watch per refresh event, so you can use it to deduplicate.

Verifying the signature

X-Vaquill-Signature is an HMAC of the request body. It is sent only when you set webhookSecret. Compute HMAC-SHA256(webhookSecret, raw_request_body_bytes) and compare it, in constant time, to the hex digest after sha256=. Use the raw bytes you received, before parsing JSON. Re-serializing the parsed object changes key order and the digest will not match.

Python

import hashlib
import hmac

def verify_signature(secret: str, raw_body: bytes, header_value: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    got = header_value.removeprefix("sha256=")
    return hmac.compare_digest(expected, got)

A watch on the email or both channel also gets an email naming the same sections.

Test before you rely on it

POST /watches/{watchId}/test sends a one-off delivery with X-Vaquill-Event: board.test. It is not saved to delivery history. You can send one test per watch every 30 seconds.

cURL

curl -X POST https://api.vaquill.ai/api/v1/watches/{watchId}/test \
  -H "Authorization: Bearer vq_key_..."

GET /watches/{watchId}/deliveries returns webhook delivery history (attempt number, status code, success, error), newest first. Email-only watches always return an empty list here.

What changed, and the diff

GET /watches/{watchId}/changes lists the sections a board added, amended, or removed, newest first. It includes changes from before you subscribed. To see only changes since you subscribed, pass since set to the watch’s createdAt. Events are kept for about five years. An empty list means we captured no change, not that a section was never amended.

curl "https://api.vaquill.ai/api/v1/watches/{watchId}/changes?limit=50" \
  -H "Authorization: Bearer vq_key_..."

changes = requests.get(
    f"https://api.vaquill.ai/api/v1/watches/{watch_id}/changes",
    headers={"Authorization": "Bearer vq_key_..."},
    params={"limit": 50},
).json()["data"]["changes"]

{
  "data": {
    "changes": [
      {
        "id": 91,
        "refreshLogId": 4412,
        "corpusType": "cfr",
        "changeKind": "amended",
        "actId": "CFR_T21_P314_S314_50",
        "citation": "21 CFR 314.50",
        "title": "Content and format of an NDA",
        "detectedAt": "2026-08-07T04:10:00Z",
        "hasDiff": false
      }
    ]
  },
  "meta": { "processingTimeMs": 12.0, "creditsConsumed": 0, "cursor": 91, "hasMore": false }
}

Polling

You can poll this endpoint as often as you like, including alongside a webhook or email watch. Polling never affects deliveries. To fetch only what is new, pass sinceId with the meta.cursor from your previous page. Ids always increase, so this never skips or repeats a change.

cURL

curl "https://api.vaquill.ai/api/v1/watches/{watchId}/changes?sinceId=91&order=asc&limit=200" \
  -H "Authorization: Bearer vq_key_..."

Python poller

Python

cursor = load_cursor()  # highest id you have processed, or None

while True:
    page = requests.get(
        f"https://api.vaquill.ai/api/v1/watches/{watch_id}/changes",
        headers={"Authorization": "Bearer vq_key_..."},
        params={"sinceId": cursor, "order": "asc", "limit": 200},
    ).json()

    for change in page["data"]["changes"]:
        handle(change)

    # Null on an empty page, so an idle poll keeps the cursor you already hold.
    if page["meta"]["cursor"] is not None:
        cursor = page["meta"]["cursor"]
        save_cursor(cursor)

    if not page["meta"]["hasMore"]:
        break

Parameter	Notes
`sinceId`	Return changes with an `id` greater than this. Use it to walk forward.
`beforeId`	Return changes with an `id` less than this. Use it to page back into history.
`since`	ISO-8601 timestamp, strictly after. Combines with `sinceId`. Less exact than `sinceId`, but useful if you only kept a `detectedAt` from a webhook body.
`changeKind`	`added`, `amended`, or `removed`. Repeat for several: `?changeKind=added&changeKind=amended`.
`order`	`desc` (default) for recent activity. `asc` when catching up from a cursor.
`limit`	1 to 200, default 50. `meta.hasMore` is true when the page filled to `limit`. Keep calling with the new cursor until it is false.

Paging backwards with beforeId

To backfill history from before you created the watch, keep order=desc and pass the lowest id you have seen as beforeId. Repeat until a page comes back empty. meta.cursor is the highest id on the page, so take the lowest id from the page yourself.

Python backfill

Python

before = None
history = []

while True:
    params = {"limit": 200, "order": "desc"}
    if before is not None:
        params["beforeId"] = before

    page = requests.get(
        f"https://api.vaquill.ai/api/v1/watches/{watch_id}/changes",
        headers={"Authorization": "Bearer vq_key_..."},
        params=params,
    ).json()

    changes = page["data"]["changes"]
    if not changes:
        break
    history.extend(changes)

    # meta.cursor is the HIGHEST id on the page, so it is the wrong end for
    # walking backwards. Take the lowest id yourself.
    before = min(c["id"] for c in changes)

    if not page["meta"]["hasMore"]:
        break

A good pattern is to use the webhook for speed and poll on a slow timer to catch deliveries your endpoint missed. Deduplicate on the change id, or on deliveryId for webhook payloads. A change can be retracted. Its id then stops appearing in the feed and its diff returns 404. Treat an id you hold that no longer appears as withdrawn. Ids are never reused.

Read the diff for one change

When hasDiff is true, call GET /watches/{watchId}/changes/{changeId}/diff for the section’s text before and after that change. It costs 4 credits, charged whether or not both sides are available, so check hasDiff first.

curl https://api.vaquill.ai/api/v1/watches/{watchId}/changes/118/diff \
  -H "Authorization: Bearer vq_key_..."

diff = requests.get(
    f"https://api.vaquill.ai/api/v1/watches/{watch_id}/changes/118/diff",
    headers={"Authorization": "Bearer vq_key_..."},
).json()["data"]

if diff["hasBefore"] and diff["hasAfter"]:
    print(diff["beforeText"])
    print(diff["afterText"])

{
  "data": {
    "changeId": 118,
    "changeKind": "amended",
    "beforeText": "An application for approval of a new drug...",
    "afterText": "An application for approval of a new drug or amended new drug...",
    "hasBefore": true,
    "hasAfter": true
  },
  "meta": { "processingTimeMs": 41.0, "creditsConsumed": 4 }
}

hasDiff (on the change) and hasBefore and hasAfter (on the diff) can be false. An added change has nothing to compare against, and corpusType=cfr never reports a diff. Every other corpus reports a diff for every amended change.

Pending Federal Rules amendments

A watch on a Federal Rule (corpusType=federal_rules) also fires when a pending amendment to that rule moves a stage. The rule’s own text has not changed on that day. An event looks like this:

{
  "changeKind": "amended",
  "actId": "FRULES_FRCP_R26",
  "lifecycleStage": "adopted_by_supreme_court",
  "relatedActId": "FRULES_FRCP_R26_P2027"
}

Field	Meaning
`changeKind`	`amended`
`actId`	The rule in force, the one you watch
`lifecycleStage`	`published_for_comment`, `approved_by_standing_committee`, `approved_by_judicial_conference`, `transmitted_to_supreme_court`, `adopted_by_supreme_court`, `transmitted_to_congress`, `in_force` or `withdrawn`
`relatedActId`	The `actId` of the proposed amendment (a `_P` document). Fetch it for the proposed text

lifecycleStage and relatedActId appear only on these events, in the change feed, in changes[] of a board.updated webhook, and on a section’s change history. A lifecycle event is not counted in sectionsAmended. FEDERAL_RULES_ANNUAL and FEDERAL_RULES_PROPOSED have no boards of their own. Watch the rule. See Federal coverage.

Data coverage

Get started

Core concepts

Guides

Bulk data and licensing

Reference

Releases

Boards and watches

Create a watch

Narrow a watch to a citation

Or watch one exact section

Authenticating our deliveries

Receiving a webhook delivery

Verifying the signature

Test before you rely on it

What changed, and the diff

Polling

Paging backwards with beforeId

Read the diff for one change

Pending Federal Rules amendments

See also