{"openapi":"3.1.0","info":{"title":"pac.dog API","version":"1.0.0","description":"The pac.dog REST API. Every browse page on pac.dog is a 1:1 mirror of one of the endpoints below — the same query helpers power both surfaces.\n\n**Authentication.** Public READ endpoints require no auth. Mutating endpoints (currently only `/api/v1/ask` and `/api/v1/ask/topup`) require either a session cookie (browser) or a Personal Access Token via `Authorization: Bearer pacd_…` (mint at `/me/tokens`).\n\n**Pagination.** Two shapes: **offset** (`?page=N&limit=N`) for analytics surfaces, **cursor** (`?cursor=<opaque>&limit=N`) for browse surfaces that must be stable under live data. Sort + filter params preserve across pages.\n\n**Sorting.** `?sort=<key>&dir=asc|desc`. Allowed sort keys are documented per endpoint; user input is validated against an allowlist server-side, so SQL injection through the sort param is structurally impossible.\n\n**Errors.** `{ \"error\": { \"code\": \"STRING_CONSTANT\", \"message\": \"...\", \"field\"?: \"...\" } }`. Stable codes (never renamed once shipped): `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `RATE_LIMITED`, `LIMIT_EXCEEDED`, `INTERNAL_ERROR`. See the README §Common error codes for the full list.\n\n**Source data.** Every row is mirrored from a primary U.S. government source — FEC, congress.gov, govinfo.gov, IRS Form 990, House Clerk / Senate LIS roll-call XML, Senate LDA, DOJ FARA, Federal Register, Regulations.gov, U.S. Census ACS, each state's Secretary of State + LegInfo / OpenLeg / IGA / WSL / OData / SOAP feed. **No third-party data vendors.** Provenance is on every detail page.","contact":{"name":"pac.dog","url":"https://pac.dog/","email":"hello@pac.dog"},"license":{"name":"Data: public domain (sources are U.S. government)."}},"servers":[{"url":"https://pac.dog/api/v1","description":"Production"}],"tags":[{"name":"Canonical graph","description":"persons, organizations, and the typed edges between them"},{"name":"Candidates","description":"FEC-registered federal candidates"},{"name":"Committees","description":"FEC-registered committees (PAC, super PAC, party, candidate)"},{"name":"Bills","description":"Federal bills (congresses 100-119) + state-leg bills"},{"name":"Members","description":"Federal members of Congress + state legislators"},{"name":"Votes","description":"House + Senate + state-leg roll-call votes"},{"name":"Nonprofits","description":"IRS 501(c)(3/4/6) + 527 organizations"},{"name":"Lobbying","description":"Federal LDA disclosures (registrants, clients, filings)"},{"name":"Federal Register","description":"FR documents + agencies + dockets"},{"name":"States","description":"Per-state hubs"},{"name":"Watchlists","description":"Public watchlists (private watchlists require auth)"},{"name":"AI","description":"/ask grounded inference + token wallet top-ups"},{"name":"Clips","description":"Quotes, mentions, posts attached to any node in the graph (Congressional Record, SERP news, press releases, ...)"},{"name":"Issues","description":"Policy-topic taxonomy + per-entity issue links + sentiment scores"},{"name":"Reference","description":"Limits, deadlines, thresholds, trends, stats, status"},{"name":"Search","description":"Semantic + name search"}],"components":{"parameters":{"page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Offset pagination — page number (1-indexed)."},"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200},"description":"Rows per page."},"sort":{"name":"sort","in":"query","schema":{"type":"string"},"description":"Sort column. Allowed values are per-endpoint; invalid values 400."},"dir":{"name":"dir","in":"query","schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction."},"cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor for cursor-paginated browse endpoints."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable error code, e.g. VALIDATION_ERROR."},"message":{"type":"string"},"field":{"type":"string","description":"Field name when the error is field-scoped."}}}}},"Person":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":"string"},"canonicalFirst":{"type":"string"},"canonicalLast":{"type":"string"},"suffix":{"type":"string","nullable":true},"birthYear":{"type":"integer","nullable":true},"gender":{"type":"string","nullable":true}}},"Organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":"string"},"kind":{"type":"string","description":"fec_committee | nonprofit | lobbying_registrant | lobbying_client | federal_agency | legislative_committee | …"},"ein":{"type":"string","nullable":true},"jurisdiction":{"type":"string","nullable":true}}},"Edge":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"edgeType":{"type":"string","description":"contributed_to, supports_independently, opposes_independently, lobbies_for, co_acted_on_bill_with, sponsor_of_bill, cosponsor_of_bill, chair_of_committee, member_of_committee, …"},"fromNodeKind":{"type":"string"},"fromNodeId":{"type":"string"},"toNodeKind":{"type":"string"},"toNodeId":{"type":"string"},"amountCents":{"type":"integer","nullable":true},"startedAt":{"type":"string","format":"date","nullable":true},"endedAt":{"type":"string","format":"date","nullable":true},"sourceKind":{"type":"string"},"confidence":{"type":"string","description":"gold | silver | bronze | manual"}}},"Candidate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fecCandidateId":{"type":"string"},"name":{"type":"string"},"party":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"office":{"type":"string","description":"P | S | H"},"district":{"type":"string","nullable":true},"isSeated":{"type":"boolean"}}},"Committee":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fecCommitteeId":{"type":"string"},"name":{"type":"string"},"committeeType":{"type":"string","nullable":true},"connectedOrg":{"type":"string","nullable":true},"cycle":{"type":"integer"}}},"Bill":{"type":"object","properties":{"id":{"type":"string","description":"Slug, e.g. \"hr1234-118\" or \"or-2025r1-hb2011\"."},"jurisdiction":{"type":"string"},"congress":{"type":"integer","nullable":true},"session":{"type":"string","nullable":true},"type":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"},"introducedAt":{"type":"string","format":"date","nullable":true}}},"Member":{"type":"object","properties":{"bioguideId":{"type":"string"},"name":{"type":"string"},"party":{"type":"string","nullable":true},"state":{"type":"string"},"chamber":{"type":"string"},"district":{"type":"string","nullable":true},"jurisdiction":{"type":"string"},"isSeated":{"type":"boolean"}}},"RollCallSummary":{"type":"object","properties":{"jurisdiction":{"type":"string"},"session":{"type":"string"},"chamber":{"type":"string"},"rollCall":{"type":"integer"},"voteDate":{"type":"string","format":"date-time"},"description":{"type":"string","nullable":true},"billId":{"type":"string","nullable":true},"totals":{"type":"object","properties":{"yea":{"type":"integer"},"nay":{"type":"integer"},"present":{"type":"integer"},"not_voting":{"type":"integer"}}}}},"LobbyingFiling":{"type":"object","properties":{"filingUuid":{"type":"string","format":"uuid"},"filingType":{"type":"string","description":"RR | Q1-Q4 | TR | YE | MR"},"filingYear":{"type":"integer"},"filingPeriod":{"type":"string","nullable":true},"incomeCents":{"type":"integer","nullable":true},"expensesCents":{"type":"integer","nullable":true},"registrantName":{"type":"string","nullable":true},"clientName":{"type":"string","nullable":true}}},"Nonprofit":{"type":"object","properties":{"ein":{"type":"string"},"name":{"type":"string"},"classification":{"type":"string","description":"e.g. 501(c)(3), 501(c)(4), 501(c)(6), 527"},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true}}},"FederalRegisterDocument":{"type":"object","properties":{"documentNumber":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","description":"Rule | Proposed Rule | Notice | Presidential Document"},"publicationDate":{"type":"string","format":"date"},"agencySlugs":{"type":"array","items":{"type":"string"}},"htmlUrl":{"type":"string","format":"uri"},"pdfUrl":{"type":"string","format":"uri","nullable":true}}},"State":{"type":"object","properties":{"code":{"type":"string","description":"USPS 2-letter (uppercase)"},"name":{"type":"string"},"members":{"type":"integer","description":"Federal members seated"},"stateLegislators":{"type":"integer"},"population":{"type":"integer","nullable":true}}},"Issue":{"type":"object","properties":{"id":{"type":"string","description":"LDA general_issue_code, e.g. HCR, BUD, TAX"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true,"description":"Economic | Environment | National Security | Social | Infrastructure | Communications | Governance"},"linkCount":{"type":"integer"}}},"Clip":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source":{"type":"string","description":"congressional_record | cspan | press_release | gdelt | state_press | x_twitter | youtube | tv_news | serp_news"},"sourceId":{"type":"string","description":"Stable per-source key (granule id, tweet id, SHA1 of result URL, …)."},"subjectKind":{"type":"string","description":"person | organization | member | candidate | committee | bill | vote | nonprofit"},"subjectId":{"type":"string","description":"Canonical id for the subject (uuid for person/org, bioguide for member, slug for bill, …)"},"speakerKind":{"type":"string","nullable":true},"speakerId":{"type":"string","nullable":true},"headline":{"type":"string"},"excerpt":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","nullable":true},"chamber":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true}}},"Watchlist":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["private","public"]},"ownerId":{"type":"string","format":"uuid"},"itemCount":{"type":"integer"}}}},"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"pacdog_session","description":"Long-lived browser session. 30-day TTL."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pacd_…","description":"Personal Access Token. Mint at /me/tokens; format `pacd_<22-char-base32>`."}}},"paths":{"/persons":{"get":{"summary":"List canonical persons (one row per real human).","tags":["Canonical graph"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Person"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/persons/{id}":{"get":{"summary":"Get one canonical person, with their cross-source aliases + top edges.","tags":["Canonical graph"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Person"},{"type":"object","properties":{"aliases":{"type":"array","items":{"type":"object"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/Edge"}}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organizations":{"get":{"summary":"List canonical organizations (committees, nonprofits, lobbying firms, agencies, legislative committees, …).","tags":["Canonical graph"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Organization"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/organizations/{id}":{"get":{"summary":"Get one canonical organization, with cross-source aliases + top edges.","tags":["Canonical graph"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Organization"},{"type":"object","properties":{"aliases":{"type":"array"},"edges":{"type":"array","items":{"$ref":"#/components/schemas/Edge"}}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organizations/{id}/lobbying-filings":{"get":{"summary":"Lobbying filings where this org is the client or the registrant.","tags":["Canonical graph","Lobbying"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"role","in":"query","schema":{"type":"string","enum":["client","registrant"]},"description":"Which side to query (default client)."},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":25}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LobbyingFiling"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/edges":{"get":{"summary":"List typed-graph edges. Filter by edge_type / from_id / to_id; sort by amount / date / type / created.","description":"Edge types: `contributed_to`, `supports_independently`, `opposes_independently`, `lobbies_for`, `co_acted_on_bill_with`, `sponsor_of_bill`, `cosponsor_of_bill`, `chair_of_committee`, `vice_chair_of_committee`, `member_of_committee`, `commented_on`, `principal_candidate_of`, `leadership_committee_of`, …","tags":["Canonical graph"],"parameters":[{"name":"type","in":"query","schema":{"type":"string"},"description":"Filter by edge_type."},{"name":"from_id","in":"query","schema":{"type":"string"},"description":"Filter by source node id."},{"name":"to_id","in":"query","schema":{"type":"string"},"description":"Filter by target node id."},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Edge"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/candidates":{"get":{"summary":"List FEC-registered federal candidates.","tags":["Candidates"],"parameters":[{"name":"state","in":"query","schema":{"type":"string"}},{"name":"party","in":"query","schema":{"type":"string"}},{"name":"office","in":"query","schema":{"type":"string","enum":["P","S","H"]}},{"name":"cycle","in":"query","schema":{"type":"integer"}},{"name":"seated","in":"query","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/candidates/{id}":{"get":{"summary":"Get one candidate (by FEC candidate id).","tags":["Candidates"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Candidate"}}}}}}},"/candidates/{id}/committees":{"get":{"summary":"Committees linked to this candidate (principal, leadership, joint fundraising).","tags":["Candidates"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Committee"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/candidates/{id}/bills":{"get":{"summary":"Bills sponsored or cosponsored by this candidate (when they served in Congress).","tags":["Candidates"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Bill"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/candidates/{id}/votes":{"get":{"summary":"Recent roll-call votes cast by this candidate (when seated).","tags":["Candidates"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/committees":{"get":{"summary":"List FEC-registered committees.","tags":["Committees"],"parameters":[{"name":"type","in":"query","schema":{"type":"string"},"description":"committee_type filter"},{"name":"cycle","in":"query","schema":{"type":"integer"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Name substring search"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Committee"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/committees/{id}":{"get":{"summary":"Get one committee (by FEC committee id).","tags":["Committees"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Committee"}}}}}}},"/bills":{"get":{"summary":"List bills (federal + state).","tags":["Bills"],"parameters":[{"name":"jurisdiction","in":"query","schema":{"type":"string"},"description":"Default `US`; otherwise USPS state code."},{"name":"congress","in":"query","schema":{"type":"integer"},"description":"Federal only."},{"name":"session","in":"query","schema":{"type":"string"},"description":"State-leg session text (e.g. `2025` for NY)."},{"name":"type","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Bill"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/bills/{id}":{"get":{"summary":"Get one bill, with sponsor + cosponsors + latest action.","tags":["Bills"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}}}}},"/bills/{id}/actions":{"get":{"summary":"Full action timeline for this bill (introduced → committee → floor → passed → enrolled → signed).","tags":["Bills"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/bills/{id}/text":{"get":{"summary":"Text versions of this bill (one row per version: IH, RH, ENR, …).","tags":["Bills"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/bills/{id}/lobbying-filings":{"get":{"summary":"LDA filings whose activity descriptions mention this bill (e.g. \"H.R. 1234\").","tags":["Bills","Lobbying"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LobbyingFiling"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/members":{"get":{"summary":"List members of Congress + state legislators.","tags":["Members"],"parameters":[{"name":"jurisdiction","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string"}},{"name":"party","in":"query","schema":{"type":"string"}},{"name":"chamber","in":"query","schema":{"type":"string"}},{"name":"seated","in":"query","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Member"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/members/{bioguide}/bills":{"get":{"summary":"Bills sponsored or cosponsored by this member.","tags":["Members"],"parameters":[{"name":"bioguide","in":"path","required":true,"schema":{"type":"string"},"description":"Federal bioguide id (e.g. `L000174`) or state-leg synthetic (e.g. `CA-LEG-A12-SMITH`)."},{"name":"role","in":"query","schema":{"type":"string","enum":["sponsor","cosponsor","any"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Bill"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/members/{bioguide}/votes":{"get":{"summary":"Recent roll-call votes cast by this member.","tags":["Members"],"parameters":[{"name":"bioguide","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/votes":{"get":{"summary":"Paginated index of distinct roll-call votes.","tags":["Votes"],"parameters":[{"name":"jurisdiction","in":"query","schema":{"type":"string"}},{"name":"congress","in":"query","schema":{"type":"integer"}},{"name":"session","in":"query","schema":{"type":"string"}},{"name":"chamber","in":"query","schema":{"type":"string","enum":["house","senate","state_upper","state_lower","unicameral"]}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RollCallSummary"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/votes/{id}":{"get":{"summary":"Roll-call detail. Tallies + per-member positions.","description":"URL form accepts two shapes: federal short (`{congress}-{house|senate}-{roll}`) or generic (`{jurisdiction}-{session}-{chamber}-{roll}`).","tags":["Votes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RollCallSummary"}}}}}}},"/nonprofits":{"get":{"summary":"List nonprofits (IRS 501(c)(3/4/6) + 527).","tags":["Nonprofits"],"parameters":[{"name":"state","in":"query","schema":{"type":"string"}},{"name":"classification","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Nonprofit"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/lobbying-filings":{"get":{"summary":"List federal LDA filings.","tags":["Lobbying"],"parameters":[{"name":"year","in":"query","schema":{"type":"integer"}},{"name":"client_id","in":"query","schema":{"type":"string"}},{"name":"registrant_id","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LobbyingFiling"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/lobbying/clients":{"get":{"summary":"List LDA clients (the entities paying for lobbying).","tags":["Lobbying"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK"}}}},"/lobbying/clients/{id}":{"get":{"summary":"Get one LDA client by source id (form `<jurisdiction>-<source_id>`).","tags":["Lobbying"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/lobbying/registrants":{"get":{"summary":"List LDA registrants (the lobbying firms).","tags":["Lobbying"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK"}}}},"/lobbying/registrants/{id}":{"get":{"summary":"Get one LDA registrant by source id.","tags":["Lobbying"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/federal-register":{"get":{"summary":"List Federal Register documents (rules, proposed rules, notices, presidential).","tags":["Federal Register"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FederalRegisterDocument"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/federal-register/{number}":{"get":{"summary":"Get one FR document by its document number.","tags":["Federal Register"],"parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FederalRegisterDocument"}}}}}}},"/federal-register/agencies":{"get":{"summary":"List Federal Register agencies (with document counts).","tags":["Federal Register"],"responses":{"200":{"description":"OK"}}}},"/federal-register/agencies/{slug}":{"get":{"summary":"Get one FR agency, with parent + sub-agencies + recent documents.","tags":["Federal Register"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/regulations/dockets":{"get":{"summary":"List Regulations.gov dockets.","tags":["Federal Register"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK"}}}},"/regulations/dockets/{id}":{"get":{"summary":"Get one docket, with contained documents.","tags":["Federal Register"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/states":{"get":{"summary":"Per-state rollup. Federal members seated, state legislators, candidates, committees, nonprofits, LDA registrants + clients, FARA, statewide population.","tags":["States"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/states/{code}":{"get":{"summary":"State hub — full payload for one state.","tags":["States"],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"USPS 2-letter (uppercase)."}}],"responses":{"200":{"description":"OK"}}}},"/watchlists":{"get":{"summary":"List public watchlists.","tags":["Watchlists"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Watchlist"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/watchlists/{slug}":{"get":{"summary":"Get one public watchlist by slug, with items.","tags":["Watchlists"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watchlist"}}}}}}},"/clips":{"get":{"summary":"List clips. Quotes, mentions, posts attached to any node in the graph.","description":"Filter by `?source` and/or `?subject_kind` + `?subject_id` (e.g. `?subject_kind=member&subject_id=L000174` for every Pelosi clip) or `?speaker_kind` + `?speaker_id` (for things this person said).","tags":["Clips"],"parameters":[{"name":"source","in":"query","schema":{"type":"string","enum":["congressional_record","cspan","press_release","gdelt","state_press","x_twitter","youtube","tv_news","serp_news"]}},{"name":"subject_kind","in":"query","schema":{"type":"string","enum":["person","organization","member","candidate","committee","bill","vote","nonprofit"]}},{"name":"subject_id","in":"query","schema":{"type":"string"}},{"name":"speaker_kind","in":"query","schema":{"type":"string"}},{"name":"speaker_id","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Clip"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/clips/{id}":{"get":{"summary":"Get one clip by uuid.","tags":["Clips"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Clip"}}}},"404":{"description":"Not found"}}}},"/issues":{"get":{"summary":"List the full issue taxonomy with link counts per issue.","tags":["Issues"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"total":{"type":"integer","description":"Total rows matching (when known)"},"page":{"type":"integer"},"pages":{"type":"integer"},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page when cursor-paginated"}}}}}}}}},"/issues/{id}":{"get":{"summary":"One issue with per-subject-kind link counts.","tags":["Issues"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issue"}}}},"404":{"description":"Not found"}}}},"/issues/{id}/subjects":{"get":{"summary":"Subjects (orgs, members, bills, ...) linked to this issue.","tags":["Issues"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"subject_kind","in":"query","schema":{"type":"string","enum":["person","organization","member","candidate","committee","bill","vote","nonprofit"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK"}}}},"/issues/trending":{"get":{"summary":"Hot issues by recent issue_link activity. Default window 30 days.","tags":["Issues"],"parameters":[{"name":"window_days","in":"query","schema":{"type":"integer","default":30}},{"name":"limit","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"OK"}}}},"/ask":{"post":{"summary":"Ask the corpus a natural-language question (signed-in only).","description":"Returns the answer as a thread row with `type='ask'`, every claim cited via @-mentions validated against the retrieved context. Pre-flight debits the wallet for the estimated cost; refusal codes cover `insufficient_balance`, `no_context`, and `model_refused`.","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"type":"string","maxLength":2000},"visibility":{"type":"string","enum":["private","public"],"default":"private"},"parentThreadId":{"type":"string","format":"uuid","nullable":true}}}}}},"responses":{"200":{"description":"Answered. Tokens charged from the wallet.","content":{"application/json":{"schema":{"type":"object","properties":{"threadId":{"type":"string","format":"uuid"},"bodyMarkdown":{"type":"string"},"tokensCharged":{"type":"integer"},"citedHandles":{"type":"array","items":{"type":"string"}},"contextHits":{"type":"integer"}}}}}},"400":{"description":"Refused (insufficient_balance, no_context, model_refused).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ask/topup":{"post":{"summary":"Create a Stripe Checkout Session for one of the preset /ask top-up packages.","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["packageId"],"properties":{"packageId":{"type":"string","enum":["usd_500","usd_1000","usd_2500","usd_5000"]}}}}}},"responses":{"200":{"description":"OK. Redirect to `url`.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"401":{"description":"Unauthorized."}}}},"/limits":{"get":{"summary":"Contribution limits, federal + all 50 states + DC, codified from statute.","tags":["Reference"],"parameters":[{"name":"jurisdiction","in":"query","schema":{"type":"string"},"description":"Default `US`."},{"name":"cycle","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/thresholds":{"get":{"summary":"Filing thresholds (PAC registration, itemization, IE-notice, electioneering) — federal + all 50 states + DC.","tags":["Reference"],"parameters":[{"name":"jurisdiction","in":"query","schema":{"type":"string"}},{"name":"cycle","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/deadlines":{"get":{"summary":"Election + filing deadlines for every cycle, federal + 50 states + DC.","tags":["Reference"],"parameters":[{"name":"jurisdiction","in":"query","schema":{"type":"string"}},{"name":"cycle","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/elections":{"get":{"summary":"List candidate-election memberships (which candidate ran in which election).","tags":["Reference"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/dir"}],"responses":{"200":{"description":"OK"}}}},"/trends":{"get":{"summary":"Aggregate trends per cycle — top donors, top IE spenders, top lobby payers.","tags":["Reference"],"parameters":[{"name":"cycle","in":"query","schema":{"type":"integer"}},{"name":"window","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/stats":{"get":{"summary":"Precomputed snapshot store. Every homepage count + /trends rollup + /status freshness row reads from here.","tags":["Reference"],"parameters":[{"name":"metric","in":"query","schema":{"type":"string"}},{"name":"key","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/status":{"get":{"summary":"Per-table data freshness + ingest health (last_attempt, last_success, consecutive_failures per source).","tags":["Reference"],"responses":{"200":{"description":"OK"}}}},"/101":{"get":{"summary":"Reference rollup for the /101 newcomer page. FEC filing-form glossary + abbreviations.","tags":["Reference"],"responses":{"200":{"description":"OK"}}}},"/search":{"get":{"summary":"Semantic search across the canonical corpus (Voyage AI embeddings, HNSW index).","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":50,"default":20}}],"responses":{"200":{"description":"OK"}}}},"/mention-search":{"get":{"summary":"Fast @-mention typeahead. ILIKE across the natural-key columns of 8 entity types.","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":20,"default":4},"description":"Per-type limit (total = limit × 8)."}],"responses":{"200":{"description":"OK"}}}}}}