Skip to main content
POST
Create a board watch

Authorizations

Authorization
string
header
required

API key issued from the developer dashboard. Pass as Authorization: Bearer vq_key_... (preferred).

Body

application/json
corpusType
enum<string>
required

Board's corpus_type (e.g. state, state_regulation, federal_register, agency_guidance). One of the published values; anything else is a 422 that lists them. Matched case-insensitively, and the uppercase search-style token for the same body of law (USC, CFR, REGULATION) is accepted and stored as the board key (REGULATION becomes state_regulation). This is the board vocabulary, not the /us/statutes/search corpusType token set: the names overlap where spelled alike (usc, cfr, state) and differ elsewhere. GET /boards says which (corpusType, state) pairs are live.

Available options:
agency_adjudication,
agency_guidance,
agency_manuals,
cfr,
federal_local_rules,
federal_primary_law,
federal_register,
federal_register_notice,
federal_rules,
session_law,
state,
state_ag_opinion,
state_constitution,
state_insurance_bulletins,
state_regulation,
state_rules,
statute_compilation,
usc
Example:

"state"

state
enum<string> | null

Board's state (2-letter, case-insensitive). For a federal board (USC, eCFR, the Federal Register) pass federal or omit this entirely; the two are equivalent. Must otherwise match the state GET /boards returned for this corpusType: GET /boards?corpusType=<type> lists exactly those.

Available options:
federal,
al,
ak,
as,
az,
ar,
ca,
co,
ct,
de,
dc,
fl,
ga,
gu,
hi,
id,
il,
in,
ia,
ks,
ky,
la,
me,
md,
ma,
mi,
mn,
ms,
mo,
mt,
ne,
nv,
nh,
nj,
nm,
ny,
nc,
nd,
mp,
oh,
ok,
or,
pa,
pr,
ri,
sc,
sd,
tn,
tx,
ut,
vt,
vi,
va,
wa,
wv,
wi,
wy
Example:

"wa"

channel
enum<string>
default:webhook
Available options:
webhook,
email,
both
webhookUrl
string | null

Required when channel is webhook or both.

webhookSecret
string | null

Optional signing secret, stored encrypted and never returned. When set, every delivery carries an X-Vaquill-Signature: sha256=<hex> header: HMAC-SHA256 of the raw request body bytes, keyed with this secret. To verify, compute the same HMAC over the raw body you received (before parsing JSON) and compare it, constant-time, to the hex digest after sha256=. Deliveries also carry Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature: v1,<base64>), signed over {webhook-id}.{webhook-timestamp}.{raw body}; prefer these, as they add replay protection. The HMAC key is the base64 decoding of the secret after whsec_ when it has that prefix, otherwise the secret's UTF-8 bytes. X-Vaquill-Signature is deprecated but remains in place for at least 12 months.

emailAddress
string | null

Required when channel is email or both.

scope
Scope · object | null

Optional narrowing so this alert covers one citation instead of an entire source. Four mutually exclusive forms. Omit entirely to watch the whole source.

Hierarchy prefix: keys title, chapter, part, section, e.g. {"title": "21", "part": "314"} for 21 CFR part 314. Every level you set must match. title is required whenever any narrower level is set, and section also needs chapter or part. Sources without a title/chapter/part hierarchy return 400 (see scopable on GET /boards).

Exact section: {"actId": "CFR_T21_P314_S314_50"}, using the actId from search results and change events. Case-sensitive and validated at create time: an act_id we do not hold, or one from a different source, is a 400. Works on every source, and is the only way to follow a single Federal Register document.

Named source: {"source": "fdic_fil"}, for corpora that fold several independent bodies of law behind one corpusType. The agency_guidance board alone carries 47 named sources across 24 agencies, so an unscoped watch on it delivers FDIC letters, IRS notices, OFAC FAQs and DOE appliance standards together. Accepted on agency_adjudication, agency_guidance, agency_manuals, cfr, federal_rules; anything else returns 400. Pickable values are on the board's sources array in GET /boards.

Publishing agency: {"agency": "irs"}, covering every source that agency issues on the board (the IRS alone publishes 5 named series). Expanded when an event is matched, not when the watch is created, so a source registered later is covered automatically. Accepted on agency_adjudication, agency_guidance, agency_manuals; pickable values are on the board's agencies array in GET /boards.

Example:
webhookAuth
WebhookAuthRequest · object | null

Optional outbound credential sent on every delivery, so your gateway can authenticate us with the header it already reads. Independent of webhookSecret: set neither, either, or both. Only valid on a webhook or both channel watch.

Response

The created watch.

data
WatchResponse · object
required
meta
ResponseMeta · object
required

The meta block every board-watch route returns beside data.