> ## 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. # List what changed on a watch's source > The sections this watch's source added, amended, or removed, newest first. This is the per-item detail behind the counts in a notification: not "3 sections changed" but which three. Covers the source's whole captured history, not just the period since you subscribed, so a watch created today can still read back what the source did before it. For the narrower 'what has my alert actually covered' view, pass `since=` the watch's own `createdAt`. History is bounded by capture, not by the age of the law: events exist only from when change capture began for that source, and are swept at 5 years. An empty list means no captured change, never 'never amended' -- the publisher's own history, where there is one, is on the section's `amendmentHistory`. **Safe to poll alongside a webhook or email watch.** This endpoint is read-only and there is no server-side 'last checked' state to interfere with: notifications fire when a corpus refresh completes, not by comparing against a watermark, and nothing here writes one. Polling cannot suppress, advance, or double-fire a delivery. (`lastNotifiedAt` on the watch records the outcome of the last delivery attempt for your visibility; it is never an input.) **Paging.** Pass `sinceId` with `meta.cursor` from your previous page to get only what is new. `meta.hasMore` is true when the page filled to `limit`, so keep calling with the new cursor until it is false. Use `order=asc` while catching up. `changeKind` is `added` (a new section), `amended` (its content was replaced), or `removed` (it disappeared from a full refresh of the source). `citation` and `title` are null for corpora that do not carry them. `detectedAt` is when OUR refresh saw the change. `sourceChangedOn`, the publisher's own date for it, is a much narrower field: we carry it on `cfr` and on no other board, so on everything else it is absent from every event. That absence is about our capture, not about the publisher, and it never licenses reading `detectedAt` as the amendment date. Check `publishesSourceChangedOn` on `GET /boards` to know which case a board is in. **Free.** ## OpenAPI ````yaml https://api.vaquill.ai/external/openapi.json get /api/v1/watches/{watch_id}/changes openapi: 3.1.0 info: title: Vaquill Developer API description: >- Public API for legal statutes and legislation. **Authentication**: Pass your API key as `Authorization: Bearer vq_key_...` (preferred) or in the `X-API-Key` header. The `api_key` query parameter also works where a header cannot be set, but a URL ends up in logs and browser history. Sending two different keys in one request is rejected with a 401. **Credits**: Each call costs API credits. See `GET /api/v1/api-credits/pricing` for the full pricing matrix. ## Jurisdictions | Jurisdiction | Coverage | `countryCode` | |---|---|---| | **United States** | USC and the Statutes at Large, the CFR and its annual editions, all 52 state and territory statutory codes (50 states plus DC and Puerto Rico), state administrative regulations, court rules, federal and state constitutions, federal agency guidance and adjudications, the Federal Register, the Sentencing Guidelines and US tax treaties. | `US` | See the full [Coverage page](https://www.vaquill.ai/docs/api-guide/coverage) for the jurisdiction-by-jurisdiction breakdown, or call `/us/statutes/coverage` for live counts. Coverage is per (jurisdiction, corpusType) pair, so treat that endpoint as the authoritative list rather than this summary. ## Endpoints - **US Statutes**: Search and retrieve any of the corpora above with full text, resolve a citation to its exact section, browse the statutory hierarchy, read a section as it stood on a past date, and follow its change history, cross-references and defined terms - **Board Watches**: Subscribe to a corpus source and get a webhook or email when it refreshes with real changes (free, API key required) - **Pricing**: Credit costs per endpoint (no auth required) ## Rate limits Limits are enforced per API key and scale with your plan. A `429` response includes a `Retry-After` header. | Plan | Per minute | Per hour | Per day | |---|---|---|---| | Vaquill API Pro | 60 | 1,000 | 2,000 | | Vaquill API Business | 150 | 2,500 | 10,000 | For full documentation, visit the [API Reference](https://www.vaquill.ai/docs/api-reference/). version: 1.0.0 contact: name: Vaquill API Support url: https://www.vaquill.ai email: support@vaquill.ai license: name: Proprietary url: https://www.vaquill.ai/terms termsOfService: https://www.vaquill.ai/terms servers: - url: https://api.vaquill.ai description: Production security: - ApiKeyAuth: [] - ApiKeyHeader: [] - ApiKeyQuery: [] tags: - name: US Statutes description: >- Search and retrieve US primary law. Covers the United States Code and the Statutes at Large, the Code of Federal Regulations and its annual editions, state statutory codes and administrative regulations, federal and state constitutions, court rules, Federal Register rules and Presidential documents, federal and state agency guidance, agency adjudications, state Attorney General opinions, the Sentencing Guidelines and US tax treaties. Scope a search with the `corpusType` filter, and call `/us/statutes/coverage` for the live jurisdiction-by-corpusType list. - **Search**: Search across all USC, CFR, state, and regulatory sections - **Section**: Get metadata, citation, hierarchy, and source links for a specific section - **Body**: Get the full text of a section - **Enactments**: Which state session laws a publisher's own tables list against a section (supported jurisdictions only, never a complete history) - name: US Session Laws description: >- State session laws: the acts of each legislature as they were enacted, chapter by chapter, before they are folded into a code. A session law is what the governor signs. It carries the act's own text, including the language it strikes and inserts, its approval and effective dates, and, where the publisher prints one, the code sections it changes. That makes it the source for "which act changed this section, and when did it take effect". Every act has a permanent `sessionLawId` (for example `SSL_MN_2025R_G_Y2025_C1`, Minnesota Laws 2025, regular session, chapter 1) whether or not we hold its text, and a citation or bill number such as `S.F.No. 1552` is accepted where an id goes. v1 serves STATE acts only. Federal session laws (the Statutes at Large, `SAL_` ids) are served by `/us/statutes/section`, and `/us/statutes/resolve` points a session-law citation here. **Start here**: check `/us/statutes/coverage` (free) for what we hold per state: each jurisdiction's `sessionLaws` block lists its sessions, which are complete or only partly collected, and the `series` and `instrumentTypes` that exist. Then **List** a session or a date range to get ids, **Get** one act for its record, then **Body** for its text. A law missing from a partly collected session is a free 404 (`session_not_fully_collected`), not proof it does not exist. - **List**: everything enacted in a state's session, approved in a window, or taking effect on a date - **Get**: one act by id or by citation; dates (`effectiveDates` is always a list), sources and the code sections it affects - **Body**: the act's text as printed, paged by cursor, with amendatory markup preserved where the publisher printed it - **Batch**: up to 50 ids or citations in one call, the same record as Get, billed per law served, with every miss listed and its reason - **Changes**: a sync feed of the registry over an integer cursor (`sinceId`): what began to be served, was corrected, withdrawn or merged The reverse link, from a code section to the acts a publisher's own tables list against it, is `GET /us/statutes/section/{actId}/enactments`. - name: Board Watches description: >- Law-change alerts. Subscribe to a **board** (a tracked corpus source, identified by `corpusType` plus an optional `state`) and get a webhook or email whenever it refreshes with real changes, naming the exact sections that changed. Fetch old-vs-new text for any amended section via the change diff. Boards refresh on their own existing cadence; watching one does not change how often it refreshes. Every endpoint here is **free**: authenticated by API key and rate-limited, but not credit-metered. See the [Law Change Alerts guide](https://www.vaquill.ai/docs/api-guide/alerts) for the full walkthrough. - name: Pricing description: >- Credit pricing and conversion rates. No authentication required. 1 credit = $0.01 USD. - name: Credits description: >- Your own credit balance: what is spendable right now, where it came from, and what is about to expire. Free and never charged, so it is safe to poll for low-balance alerting or to pre-flight a batch job. externalDocs: description: Full API Reference url: https://www.vaquill.ai/docs/api-reference/ paths: /api/v1/watches/{watch_id}/changes: get: tags: - Board Watches summary: List what changed on a watch's source description: >- The sections this watch's source added, amended, or removed, newest first. This is the per-item detail behind the counts in a notification: not "3 sections changed" but which three. Covers the source's whole captured history, not just the period since you subscribed, so a watch created today can still read back what the source did before it. For the narrower 'what has my alert actually covered' view, pass `since=` the watch's own `createdAt`. History is bounded by capture, not by the age of the law: events exist only from when change capture began for that source, and are swept at 5 years. An empty list means no captured change, never 'never amended' -- the publisher's own history, where there is one, is on the section's `amendmentHistory`. **Safe to poll alongside a webhook or email watch.** This endpoint is read-only and there is no server-side 'last checked' state to interfere with: notifications fire when a corpus refresh completes, not by comparing against a watermark, and nothing here writes one. Polling cannot suppress, advance, or double-fire a delivery. (`lastNotifiedAt` on the watch records the outcome of the last delivery attempt for your visibility; it is never an input.) **Paging.** Pass `sinceId` with `meta.cursor` from your previous page to get only what is new. `meta.hasMore` is true when the page filled to `limit`, so keep calling with the new cursor until it is false. Use `order=asc` while catching up. `changeKind` is `added` (a new section), `amended` (its content was replaced), or `removed` (it disappeared from a full refresh of the source). `citation` and `title` are null for corpora that do not carry them. `detectedAt` is when OUR refresh saw the change. `sourceChangedOn`, the publisher's own date for it, is a much narrower field: we carry it on `cfr` and on no other board, so on everything else it is absent from every event. That absence is about our capture, not about the publisher, and it never licenses reading `detectedAt` as the amendment date. Check `publishesSourceChangedOn` on `GET /boards` to know which case a board is in. **Free.** operationId: list_watch_changes_api_v1_watches__watch_id__changes_get parameters: - name: watch_id in: path required: true schema: type: string title: Watch Id - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: Max changes to return. default: 50 title: Limit description: Max changes to return. - name: sinceId in: query required: false schema: anyOf: - type: integer minimum: 0 - type: 'null' description: >- Return only changes with an `id` greater than this. The cursor to build on: ids are a monotonic sequence, so this is exact, immune to clock skew, and cannot drop two changes that share a timestamp. Carry `meta.cursor` forward from your last page. title: Sinceid description: >- Return only changes with an `id` greater than this. The cursor to build on: ids are a monotonic sequence, so this is exact, immune to clock skew, and cannot drop two changes that share a timestamp. Carry `meta.cursor` forward from your last page. - name: beforeId in: query required: false schema: anyOf: - type: integer minimum: 0 - type: 'null' description: >- Return only changes with an `id` less than this: the cursor for walking BACK through history, where `sinceId` walks forward into new changes. A newest-first reader needs this one, since paging down a descending list means asking for what sits below the lowest id already held. Pass the smallest `id` on your last page. title: Beforeid description: >- Return only changes with an `id` less than this: the cursor for walking BACK through history, where `sinceId` walks forward into new changes. A newest-first reader needs this one, since paging down a descending list means asking for what sits below the lowest id already held. Pass the smallest `id` on your last page. - name: since in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Return only changes detected strictly after this ISO-8601 timestamp. Coarser than `sinceId` (a single refresh writes many rows at the same instant, and this drops all of them), but useful when all you kept was the `detectedAt` off a `changes[]` item in a webhook body. Prefer that item's `id` as `sinceId` where you still have it. Both may be combined. examples: - '2026-08-07T04:10:00Z' title: Since description: >- Return only changes detected strictly after this ISO-8601 timestamp. Coarser than `sinceId` (a single refresh writes many rows at the same instant, and this drops all of them), but useful when all you kept was the `detectedAt` off a `changes[]` item in a webhook body. Prefer that item's `id` as `sinceId` where you still have it. Both may be combined. - name: changeKind in: query required: false schema: anyOf: - type: array items: enum: - added - amended - removed type: string - type: 'null' description: >- Filter to these kinds. Repeat the parameter to pass several (`?changeKind=added&changeKind=amended`). Omit for all three. title: Changekind description: >- Filter to these kinds. Repeat the parameter to pass several (`?changeKind=added&changeKind=amended`). Omit for all three. - name: order in: query required: false schema: enum: - asc - desc type: string description: >- `desc` (default) is newest first, for showing a recent-activity list. Use `asc` when catching up from a cursor: walking forward means a page that hits `limit` leaves the gap at a known end. default: desc title: Order description: >- `desc` (default) is newest first, for showing a recent-activity list. Use `asc` when catching up from a cursor: walking forward means a page that hits `limit` leaves the gap at a known end. responses: '200': description: What changed, newest first. content: application/json: schema: {} example: 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' sourceChangedOn: '2026-08-05' hasDiff: false meta: processingTimeMs: 12 creditsConsumed: 0 cursor: 91 hasMore: false '400': description: Invalid changeKind, order, or since timestamp. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' '403': description: API key lacks `research:read` scope. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' '404': description: Watch not found. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ApiDetailError' components: schemas: ApiDetailError: properties: detail: type: string title: Detail description: >- Human-readable reason, safe to surface to an end user. Branch on the HTTP status rather than on this string: the wording is not part of the contract and may be reworded, but 401 (bad key), 402 (out of credits), 403 (missing scope), 404 (no such resource) and 429 (rate limited) are stable. examples: - Insufficient API credits. errors: anyOf: - items: $ref: '#/components/schemas/ApiFieldError' type: array - type: 'null' title: Errors description: 'Present on 422 only: every field that failed validation.' type: object required: - detail title: ApiDetailError description: >- Error envelope the API actually returns. Every error (400/401/402/403/404/405/422/429/5xx) carries a `detail` string, e.g. `{"detail": "Insufficient API credits."}`, on every mount of the API. A 422 adds `errors`, one entry per rejected field. Some 404s add endpoint-specific diagnosis beside `detail` (the statutes section routes add `actId`, `reason` and `didYouMean`); treat unknown keys as optional. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ApiFieldError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Loc description: >- Where the bad value is: `body`, `query` or `path`, then the parameter name exactly as you send it (camelCase), then list indexes. A bare `["body"]` means the body as a whole was not a JSON object. examples: - - body - corpusType msg: type: string title: Msg description: What is wrong with the value, in plain English. examples: - Input should be 'USC', 'CFR' or 'STATE' type: type: string title: Type description: >- Machine-readable error kind, e.g. `missing`, `literal_error`, `json_invalid`. examples: - literal_error type: object required: - loc - msg - type title: ApiFieldError description: One rejected field in a 422 response. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: vq_key_* description: >- API key issued from the developer dashboard. Pass as `Authorization: Bearer vq_key_...` (preferred). ApiKeyHeader: type: apiKey in: header name: X-API-Key description: >- The same API key as a bare header value: `X-API-Key: vq_key_...`. Equivalent to the Bearer form. ApiKeyQuery: type: apiKey in: query name: api_key description: >- The same API key as a query parameter: `?api_key=vq_key_...`. Use only where you cannot set a header. A URL can end up in proxy and server logs, browser history and shared links, so prefer either header form, and rotate a key that has leaked. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.