{ "openapi": "3.1.0", "info": { "title": "POPVOX public appropriations snapshot API", "version": "1.0.0", "description": "Public read-only access to the source-linked House CPF and Senate CDS Explorer snapshots and ApproPRO funding reference catalog. 120 requests/minute per client IP, maximum 200 rows/page. GET, HEAD and OPTIONS; public CORS; ETag revalidation. No additional compilation license is asserted; source rights and terms remain applicable. Not an official product of Congress." }, "servers": [ { "url": "https://popvox.com/api/explorer/appropriations/v1" } ], "security": [], "paths": { "/snapshot": { "get": { "summary": "Load a complete chamber release for the Explorer", "description": "Complete source fields and metadata for the selected database release. Supports HTTP gzip. Use /records for bounded pagination; this endpoint intentionally returns the complete chamber snapshot.", "parameters": [ { "name": "chamber", "in": "query", "required": true, "description": "Select one chamber.", "schema": { "type": "string", "enum": [ "house", "senate" ] } }, { "name": "snapshot", "in": "query", "required": false, "description": "Carry meta.snapshot from the first page. A changed snapshot returns 409; restart pagination.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Successful snapshot query.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "ETag unchanged." }, "400": { "description": "Invalid or repeated parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "URL exceeds 4096 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Snapshot unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/datasets": { "get": { "summary": "Discover datasets, downloads, hashes and coverage", "description": "No account or API key is required. Sources have independent publication, retrieval and export dates.", "parameters": [], "security": [], "responses": { "200": { "description": "Successful snapshot query.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "ETag unchanged." }, "400": { "description": "Invalid or repeated parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "URL exceeds 4096 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Snapshot unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/records": { "get": { "summary": "Filter House or Senate funding records", "description": "Stable record-ID ordering. Totals are calculated over all matching records before pagination and separately for each stage.", "parameters": [ { "name": "chamber", "in": "query", "required": true, "description": "Select one chamber.", "schema": { "type": "string", "enum": [ "house", "senate" ] } }, { "name": "fiscal_year", "in": "query", "required": false, "description": "Fiscal year. Records currently cover FY2027; the funding catalog covers FY2026 and FY2027.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2200 } }, { "name": "stage", "in": "query", "required": false, "description": "House aggregates require an explicit stage. Senate supports requested only.", "schema": { "type": "string", "enum": [ "requested", "included_in_house_bill" ] } }, { "name": "state", "in": "query", "required": false, "description": "Senate project state, or House reported state (which can be a recipient address).", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "member_id", "in": "query", "required": false, "description": "Bioguide Member identifier.", "schema": { "type": "string", "pattern": "^[A-Z][0-9]{6}$" } }, { "name": "subcommittee_id", "in": "query", "required": false, "description": "Exact source subcommittee ID, e.g. senate-approps-interior.", "schema": { "type": "string" } }, { "name": "funding_account_id", "in": "query", "required": false, "description": "Exact POPVOX funding-account ID; Senate has no assigned accounts.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive literal substring across names, purpose, place, and account label. Not semantic search or topic classification.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "amount_min", "in": "query", "required": false, "description": "Inclusive amount bound in whole USD; unknown amounts are excluded.", "schema": { "type": "integer", "minimum": 0, "maximum": 90071992547409 } }, { "name": "amount_max", "in": "query", "required": false, "description": "Inclusive amount bound in whole USD; unknown amounts are excluded.", "schema": { "type": "integer", "minimum": 0, "maximum": 90071992547409 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records or groups per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Start offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 200000, "default": 0 } }, { "name": "snapshot", "in": "query", "required": false, "description": "Carry meta.snapshot from the first page. A changed snapshot returns 409; restart pagination.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Successful snapshot query.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "ETag unchanged." }, "400": { "description": "Invalid or repeated parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "URL exceeds 4096 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Snapshot unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/record": { "get": { "summary": "Read a record with original fields and sources", "description": "Source connections remain candidates. Current roster observations are not verified facts at submission time.", "parameters": [ { "name": "chamber", "in": "query", "required": true, "description": "Select one chamber.", "schema": { "type": "string", "enum": [ "house", "senate" ] } }, { "name": "record_id", "in": "query", "required": true, "description": "Exact source record ID. Historical House aliases resolve to the corrected record.", "schema": { "type": "string" } }, { "name": "snapshot", "in": "query", "required": false, "description": "Carry meta.snapshot from the first page. A changed snapshot returns 409; restart pagination.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Successful snapshot query.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Record" }, { "type": "object", "properties": { "source_record": { "type": "object" }, "members": { "type": "array", "items": { "type": "object" } }, "source": { "type": [ "object", "null" ] }, "candidate_connections": { "type": "array", "items": { "type": "object" } } } } ] }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "ETag unchanged." }, "400": { "description": "Invalid or repeated parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "URL exceeds 4096 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Snapshot unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/aggregates": { "get": { "summary": "Compute exact gross totals within one stage", "description": "House stage is required. meta.matching_records counts each source record once; pagination applies to groups.", "parameters": [ { "name": "chamber", "in": "query", "required": true, "description": "Select one chamber.", "schema": { "type": "string", "enum": [ "house", "senate" ] } }, { "name": "fiscal_year", "in": "query", "required": false, "description": "Fiscal year. Records currently cover FY2027; the funding catalog covers FY2026 and FY2027.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2200 } }, { "name": "stage", "in": "query", "required": false, "description": "House aggregates require an explicit stage. Senate supports requested only.", "schema": { "type": "string", "enum": [ "requested", "included_in_house_bill" ] } }, { "name": "state", "in": "query", "required": false, "description": "Senate project state, or House reported state (which can be a recipient address).", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "member_id", "in": "query", "required": false, "description": "Bioguide Member identifier.", "schema": { "type": "string", "pattern": "^[A-Z][0-9]{6}$" } }, { "name": "subcommittee_id", "in": "query", "required": false, "description": "Exact source subcommittee ID, e.g. senate-approps-interior.", "schema": { "type": "string" } }, { "name": "funding_account_id", "in": "query", "required": false, "description": "Exact POPVOX funding-account ID; Senate has no assigned accounts.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive literal substring across names, purpose, place, and account label. Not semantic search or topic classification.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "amount_min", "in": "query", "required": false, "description": "Inclusive amount bound in whole USD; unknown amounts are excluded.", "schema": { "type": "integer", "minimum": 0, "maximum": 90071992547409 } }, { "name": "amount_max", "in": "query", "required": false, "description": "Inclusive amount bound in whole USD; unknown amounts are excluded.", "schema": { "type": "integer", "minimum": 0, "maximum": 90071992547409 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records or groups per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Start offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 200000, "default": 0 } }, { "name": "snapshot", "in": "query", "required": false, "description": "Carry meta.snapshot from the first page. A changed snapshot returns 409; restart pagination.", "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "required": false, "description": "Member groups attribute the full amount to each listed Member and must not be summed. Null keys retain unknown assignments.", "schema": { "type": "string", "enum": [ "state", "member", "subcommittee", "account" ], "default": "subcommittee" } } ], "security": [], "responses": { "200": { "description": "Successful snapshot query.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Totals" }, { "type": "object", "properties": { "key": { "type": [ "string", "null" ] } } } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "ETag unchanged." }, "400": { "description": "Invalid or repeated parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "URL exceeds 4096 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Snapshot unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/funding-lines": { "get": { "summary": "Look up funding guidance by chamber, year and request type", "description": "Missing years return guidance_pending with zero lines. There is no prior-year fallback. This reference does not certify eligibility or supply Treasury identifiers.", "parameters": [ { "name": "chamber", "in": "query", "required": true, "description": "Select one chamber.", "schema": { "type": "string", "enum": [ "house", "senate" ] } }, { "name": "fiscal_year", "in": "query", "required": true, "description": "Fiscal year. Records currently cover FY2027; the funding catalog covers FY2026 and FY2027.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2200 } }, { "name": "request_type", "in": "query", "required": true, "description": "House uses cpf; Senate uses cds. Programmatic and language requests return not_catalogued.", "schema": { "type": "string", "enum": [ "cpf", "cds", "programmatic", "language" ] } }, { "name": "subcommittee_key", "in": "query", "required": false, "description": "Catalog key, e.g. int for Interior. This differs from the source subcommittee_id.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search the catalog labels, agencies, accounts and programs.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records or groups per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Start offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 200000, "default": 0 } }, { "name": "snapshot", "in": "query", "required": false, "description": "Carry meta.snapshot from the first page. A changed snapshot returns 409; restart pagination.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Successful snapshot query.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "official_label", "evidence" ], "properties": { "id": { "type": "string" }, "official_label": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object" } }, "agency": { "type": "object" }, "account": { "type": [ "object", "null" ] }, "programs": { "type": "array", "items": { "type": "object" } } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "304": { "description": "ETag unchanged." }, "400": { "description": "Invalid or repeated parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Read-only service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "URL exceeds 4096 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Snapshot unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Record": { "type": "object", "required": [ "record_id", "chamber", "fiscal_year", "stage", "amount_usd", "amount_cents", "member_ids", "detail_url" ], "properties": { "record_id": { "type": "string" }, "source_stage": { "type": "string" }, "recipient_name": { "type": "string" }, "member_display": { "type": "string" }, "location_basis": { "type": "string" }, "subcommittee_id": { "type": "string" }, "account_status": { "type": "string" }, "detail_url": { "type": "string" }, "chamber": { "type": "string", "enum": [ "house", "senate" ] }, "fiscal_year": { "type": "integer" }, "stage": { "type": "string", "enum": [ "requested", "included_in_house_bill" ] }, "currency": { "const": "USD" }, "member_ids": { "type": "array", "items": { "type": "string" } }, "project_name": { "type": [ "string", "null" ] }, "purpose": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "account_label": { "type": [ "string", "null" ] }, "funding_account_id": { "type": [ "string", "null" ] }, "funding_line_id": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "source_retrieved_at": { "type": [ "string", "null" ] }, "source_sha256": { "type": [ "string", "null" ] }, "amount_usd": { "type": [ "number", "null" ] }, "amount_cents": { "type": [ "integer", "null" ] }, "source_page": { "type": [ "integer", "null" ] }, "source_row": { "type": [ "integer", "null" ] } } }, "Totals": { "type": "object", "required": [ "record_count", "known_amount_count", "unknown_amount_count", "gross_amount_cents", "gross_amount_usd" ], "properties": { "record_count": { "type": "integer" }, "known_amount_count": { "type": "integer" }, "unknown_amount_count": { "type": "integer" }, "gross_amount_cents": { "type": [ "integer", "null" ] }, "gross_amount_usd": { "type": [ "number", "null" ] } } }, "Meta": { "type": "object", "required": [ "snapshot" ], "properties": { "snapshot": { "type": "string" }, "storage": { "type": "string", "enum": [ "popvox_database", "file_snapshot" ] }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "totals_by_stage": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Totals" } }, "matching_records": { "$ref": "#/components/schemas/Totals" }, "coverage": { "description": "Original snapshot coverage or scoped catalog guidance status." } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }