API documentation

Public appropriations API

Beta. No account or API key required.

The appropriations API covers Senate community project requests, House community project records, and funding account guidance. Responses retain source links, dates and coverage notes.

curl --fail-with-body \
  'https://popvox.com/api/explorer/appropriations/v1/records?chamber=senate&state=MD&limit=5'

Requests and bill inclusions are different stages. Neither establishes an enacted appropriation or an award. House request coverage is incomplete, and Senate bill-inclusion tables are not included.

Base URL: https://popvox.com/api/explorer/appropriations/v1. Up to 200 records per page and 120 requests per minute per client IP. Public CORS supports browser applications. Bulk downloads are listed below.

Authenticated API

These endpoints require approved dataset permissions and a bearer key. Access requests and key management are handled through the POPVOX Hub.

Base URL: https://popvox.com/api/data/v1. An invitation alone does not grant every dataset; each key is limited to its approved scopes.

Authentication example

Store your key in a server-side secret named POPVOX_API_KEY. Send it in the Authorization header, never in a URL or public browser code. This example requires hearings:read.

curl --fail-with-body \
  -H "Authorization: Bearer ${POPVOX_API_KEY}" \
  'https://popvox.com/api/data/v1/meetings?chamber=House&event_type=Hearing&limit=5'

The OpenAPI file describes request parameters, response fields, required scopes and error responses. Preserve meta.freshness, source identifiers and coverage gaps when storing results. API freshness is independent of the Explorer build dates in the catalog.

Use the source endpoint for your approved family. Unfiltered /sources requires all three original scopes: staff, Members and committees. Lobbying and FARA currently have Explorer snapshots, not partner API endpoints.

Pagination and errors

Both APIs return data and meta. Begin with your filters and a limit of up to 200. Carry meta.snapshot and meta.next_offset into subsequent requests, retaining the original filters. Stop when next_offset is null.

const base = 'https://popvox.com/api/explorer/appropriations/v1/records';
const params = new URLSearchParams({ chamber: 'senate', state: 'MD', limit: '200' });
const records = [];
for (;;) {
  const response = await fetch(`${base}?${params}`);
  if (!response.ok) throw new Error(`HTTP ${response.status}; see the error guide`);
  const { data, meta } = await response.json();
  records.push(...data);
  if (meta.next_offset === null) break;
  params.set('snapshot', meta.snapshot);
  params.set('offset', meta.next_offset);
}

For a partner endpoint, use the same pagination pattern from your server, with its approved filters and Authorization header. Partner offsets are bounded at 200,000; narrow your filters for larger result sets.