{ "openapi": "3.0.3", "info": { "title": "CIV.IQ Public API", "description": "Open REST API for normalized U.S. government data — federal and state legislators, bills, votes, campaign finance, lobbying, and ML-powered intelligence analysis. No API key required. Rate limited to 60 requests/minute per IP.\n\n## Rate limiting\n\nResponses carry the IETF RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset / RateLimit-Policy headers (plus the legacy X-RateLimit-* trio); a 429 includes Retry-After.\n\n## Versioning & deprecation policy\n\nThe API is versioned in the URL path (/api/v1); every v1 response carries X-API-Version. Additive changes ship within v1 and are recorded at GET /v1/changelog. Breaking changes only ship as a new URL version. Before any version is retired, its responses will carry Deprecation and Sunset headers (RFC 8594) plus Link rel=\"successor-version\" at least 6 months before shutdown. No version is currently deprecated. Full policy: https://civdotiq.org/docs/api#versioning\n\n## Errors\n\nEvery error is structured JSON: v1 endpoints return V1Error (integer code + meta), non-v1 endpoints return ApiError (string code + metadata). Unknown API paths return a JSON 404, never HTML.", "version": "1.2.1", "license": { "name": "MIT", "url": "https://github.com/civdotiq/civ.iq/blob/main/LICENSE" }, "contact": { "name": "CIV.IQ", "url": "https://civdotiq.org" } }, "servers": [ { "url": "https://civdotiq.org/api", "description": "Production" } ], "paths": { "/v1/": { "get": { "summary": "API index", "description": "Lists all available v1 endpoints with descriptions.", "operationId": "getIndex", "tags": ["Index"], "responses": { "200": { "description": "API index with endpoint listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/analytics": { "get": { "summary": "Per-endpoint request counts", "description": "Returns request counts per endpoint for a given date range. Authenticated with a bearer token (CACHE_WARM_SECRET). Intended for operational observability — not part of the citizen-facing read path.", "operationId": "getAnalytics", "tags": ["Analytics"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "description": "Range start (YYYY-MM-DD). Defaults to 7 days before today.", "example": "2026-04-13" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "description": "Range end (YYYY-MM-DD). Defaults to today.", "example": "2026-04-20" } ], "responses": { "200": { "description": "Request counts for the date range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/representatives": { "get": { "summary": "List representatives", "description": "List all current members of Congress with optional filtering.", "operationId": "listRepresentatives", "tags": ["Representatives"], "parameters": [ { "name": "chamber", "in": "query", "schema": { "type": "string", "enum": ["house", "senate"] }, "description": "Filter by chamber" }, { "name": "state", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "Two-letter state code (e.g., MI)" }, { "name": "party", "in": "query", "schema": { "type": "string", "enum": ["D", "R", "I"] }, "description": "Filter by party" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 535 }, "description": "Results per page" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "List of representatives", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepresentativeListResponse" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/representatives/{bioguideId}": { "get": { "summary": "Get representative detail", "description": "Get detailed info for a specific member of Congress.", "operationId": "getRepresentative", "tags": ["Representatives"], "parameters": [ { "name": "bioguideId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]\\d{6}$" }, "description": "Bioguide ID (e.g., P000197)", "example": "P000197" } ], "responses": { "200": { "description": "Representative detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepresentativeDetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/bills": { "get": { "summary": "List bills", "description": "List latest bills from Congress.", "operationId": "listBills", "tags": ["Bills"], "parameters": [ { "name": "congress", "in": "query", "schema": { "type": "integer", "minimum": 93, "default": 119 }, "description": "Congress number (93 or later, up to the current Congress). Defaults to the current Congress." }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "updateDate+desc", "enum": [ "updateDate+desc", "updateDate+asc", "number+desc", "number+asc" ] }, "description": "Sort order" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 250 }, "description": "Results per page" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "List of bills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillListResponse" } } } }, "502": { "$ref": "#/components/responses/BadGateway" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/bills/{billId}": { "get": { "summary": "Get bill detail", "description": "Get bill detail from Congress.gov.", "operationId": "getBill", "tags": ["Bills"], "parameters": [ { "name": "billId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bill ID in format: {congress}-{type}-{number}", "example": "119-hr-1" } ], "responses": { "200": { "description": "Bill detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillDetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/BadGateway" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/bills/{billId}/summary": { "get": { "summary": "Get bill summary", "description": "Get cached AI-generated plain-language summary. Does not trigger live generation.", "operationId": "getBillSummary", "tags": ["Bills"], "parameters": [ { "name": "billId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bill ID in format: {congress}-{type}-{number}", "example": "119-hr-1" } ], "responses": { "200": { "description": "Bill summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillSummaryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/votes/{voteId}": { "get": { "summary": "Get vote detail", "description": "Get roll-call vote details including individual member positions.", "operationId": "getVote", "tags": ["Votes"], "parameters": [ { "name": "voteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vote ID in format: {chamber}-{congress}-{rollNumber}", "example": "house-119-116" } ], "responses": { "200": { "description": "Vote detail with positions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteDetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/BadGateway" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/districts/{districtId}": { "get": { "summary": "Get district detail", "description": "Get district info and its representatives.", "operationId": "getDistrict", "tags": ["Districts"], "parameters": [ { "name": "districtId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}-(\\d{1,2}|AL)$" }, "description": "District ID in format: {state}-{district}", "example": "MI-12" } ], "responses": { "200": { "description": "District detail with representatives", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistrictDetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/committees": { "get": { "summary": "List committees", "description": "List congressional committees.", "operationId": "listCommittees", "tags": ["Committees"], "parameters": [ { "name": "chamber", "in": "query", "schema": { "type": "string" }, "description": "Filter by chamber" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 250 }, "description": "Results per page" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "List of committees", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitteeListResponse" } } } }, "502": { "$ref": "#/components/responses/BadGateway" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/committees/{committeeId}": { "get": { "summary": "Get committee detail", "description": "Get committee detail with members and subcommittees.", "operationId": "getCommittee", "tags": ["Committees"], "parameters": [ { "name": "committeeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Committee system code", "example": "HSJU" } ], "responses": { "200": { "description": "Committee detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitteeDetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/changelog": { "get": { "summary": "API changelog", "description": "Version history with change descriptions.", "operationId": "getChangelog", "tags": ["Index"], "responses": { "200": { "description": "Changelog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangelogResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/mcp": { "get": { "summary": "MCP server (stream/discovery)", "description": "Streamable HTTP transport endpoint for MCP. GET is used by clients that negotiate SSE or poll for server-sent events. See https://modelcontextprotocol.io", "operationId": "mcpStream", "tags": ["MCP"], "responses": { "200": { "description": "MCP protocol response" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "405": { "description": "GET without an SSE Accept header (text/event-stream required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } } }, "500": { "description": "Unexpected server error (JSON-RPC envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } } } } }, "post": { "summary": "MCP server", "description": "Model Context Protocol endpoint for AI assistant integration. 47 tools, 3 resources, 3 prompts. See https://modelcontextprotocol.io", "operationId": "mcpServer", "tags": ["MCP"], "responses": { "200": { "description": "MCP protocol response" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "400": { "description": "Malformed JSON-RPC request or unacceptable Accept header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } } }, "500": { "description": "Unexpected server error (JSON-RPC envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } } } } }, "delete": { "summary": "MCP session termination", "description": "Terminates an MCP session initiated via the streamable HTTP transport. Required by the MCP specification for clean shutdown.", "operationId": "mcpSessionDelete", "tags": ["MCP"], "responses": { "200": { "description": "Session terminated" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Unexpected server error (JSON-RPC envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } } } } } } }, "/intelligence/representative/{bioguideId}/influence-chain": { "get": { "summary": "Influence chain analysis", "description": "Traces lobbying money through contributions, committee assignments, and votes. Shows the path from lobbying organizations to legislative outcomes.", "operationId": "getInfluenceChain", "tags": ["Intelligence"], "parameters": [ { "name": "bioguideId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bioguide ID", "example": "P000197" } ], "responses": { "200": { "description": "Influence chain insight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntelligenceInsightResponse" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/intelligence/representative/{bioguideId}/temporal": { "get": { "summary": "Temporal voting analysis", "description": "Quarterly voting pattern shifts over time. Shows how a legislator's alignment has changed across quarters.", "operationId": "getTemporalAnalysis", "tags": ["Intelligence"], "parameters": [ { "name": "bioguideId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bioguide ID", "example": "P000197" } ], "responses": { "200": { "description": "Temporal voting insight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntelligenceInsightResponse" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/intelligence/representative/{bioguideId}/finance-jurisdiction": { "get": { "summary": "Finance-jurisdiction overlap", "description": "Analyzes overlap between a legislator's campaign finance sources and their committee jurisdictions.", "operationId": "getFinanceJurisdiction", "tags": ["Intelligence"], "parameters": [ { "name": "bioguideId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bioguide ID", "example": "P000197" } ], "responses": { "200": { "description": "Finance-jurisdiction overlap insight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntelligenceInsightResponse" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/intelligence/sector/{sector}/leaderboard": { "get": { "summary": "Sector donation leaderboard", "description": "Top recipients of campaign contributions from a specific industry sector.", "operationId": "getSectorLeaderboard", "tags": ["Intelligence"], "parameters": [ { "name": "sector", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Industry sector name (e.g., Defense, Health, Energy)", "example": "Defense" }, { "name": "chamber", "in": "query", "schema": { "type": "string", "enum": ["house", "senate"] }, "description": "Filter by chamber" }, { "name": "party", "in": "query", "schema": { "type": "string", "enum": ["D", "R", "I"] }, "description": "Filter by party" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "Number of results" } ], "responses": { "200": { "description": "Sector leaderboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectorLeaderboardResponse" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/intelligence/address/money-report": { "get": { "summary": "Money report by ZIP code", "description": "Campaign finance report card for representatives serving a ZIP code. ZIP-based responses include `accuracyNote` and `status: 'partial'` — ZIP ↔ congressional district alignment is 10–20% wrong. For authoritative results, use the address POST endpoint.", "operationId": "getMoneyReportByZip", "tags": ["Intelligence"], "parameters": [ { "name": "zip", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{5}$" }, "description": "5-digit ZIP code", "example": "48226" } ], "responses": { "200": { "description": "Money report for ZIP (approximate — see accuracyNote)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoneyReportResponse" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } }, "post": { "summary": "Money report by address", "description": "Campaign finance report card for representatives serving a street address.", "operationId": "getMoneyReportByAddress", "tags": ["Intelligence"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "street": { "type": "string", "example": "1600 Pennsylvania Ave" }, "city": { "type": "string", "example": "Washington" }, "state": { "type": "string", "example": "DC" } }, "required": ["street", "city", "state"] } } } }, "responses": { "200": { "description": "Money report for address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoneyReportResponse" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/intelligence/address/representatives": { "post": { "summary": "Representatives by address", "description": "Look up all federal representatives (House + Senate) for a street address. Address-based responses do NOT include `accuracyNote` — the district is authoritative.", "operationId": "getRepresentativesByAddress", "tags": ["Intelligence"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "street": { "type": "string", "example": "1600 Pennsylvania Ave" }, "city": { "type": "string", "example": "Washington" }, "state": { "type": "string", "example": "DC" } }, "required": ["street", "city", "state"] } } } }, "responses": { "200": { "description": "Representatives for address", "content": { "application/json": { "schema": { "type": "object", "properties": { "representatives": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentativeSummary" } }, "state": { "type": "string" }, "district": { "type": "string" }, "multiDistrict": { "type": "boolean" }, "accuracyNote": { "type": "string", "description": "Populated only on ZIP-based GET responses (not address POST). Communicates that ZIP ↔ district alignment is 10–20% wrong and address-based lookup is preferred for authoritative results." }, "status": { "type": "string", "enum": ["complete", "partial", "unavailable"], "description": "'partial' when accuracyNote is set (ZIP input); 'complete' for address input." }, "dataQuality": { "$ref": "#/components/schemas/DataQuality" }, "sourceStatus": { "type": "array", "items": { "$ref": "#/components/schemas/SourceStatus" } } } } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } }, "get": { "summary": "Representatives by ZIP code", "description": "ZIP-code fallback for the address-based lookup. Responses include `accuracyNote` and `status: 'partial'` because ZIP ↔ district alignment is 10–20% wrong; prefer the address POST endpoint for authoritative results.", "operationId": "getRepresentativesByZip", "tags": ["Intelligence"], "parameters": [ { "name": "zip", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{5}$" }, "description": "5-digit ZIP code", "example": "48226" } ], "responses": { "200": { "description": "Representatives for ZIP (approximate — see accuracyNote)", "content": { "application/json": { "schema": { "type": "object", "properties": { "representatives": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentativeSummary" } }, "state": { "type": "string" }, "district": { "type": "string" }, "multiDistrict": { "type": "boolean" }, "accuracyNote": { "type": "string", "description": "Present on ZIP-based responses. ZIP ↔ district alignment is 10–20% wrong; use address POST for authoritative results." }, "status": { "type": "string", "enum": ["partial", "unavailable"] }, "dataQuality": { "$ref": "#/components/schemas/DataQuality" }, "sourceStatus": { "type": "array", "items": { "$ref": "#/components/schemas/SourceStatus" } } } } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/intelligence/influence-clusters": { "get": { "summary": "Influence clusters", "description": "Legislators grouped by shared funding patterns. Reveals cross-party clusters with similar donor profiles.", "operationId": "getInfluenceClusters", "tags": ["Intelligence"], "parameters": [ { "name": "bioguideId", "in": "query", "schema": { "type": "string" }, "description": "Optional: get cluster for a specific legislator" } ], "responses": { "200": { "description": "Influence clusters", "content": { "application/json": { "schema": { "type": "object", "properties": { "clusters": { "type": "array", "items": { "type": "object" } }, "crossPartyHighlights": { "type": "array", "items": { "type": "object" } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/search/unified": { "get": { "summary": "Unified search", "description": "Cross-domain search across representatives, bills, committees, and state legislators. Supports state prefix (e.g., CA:pelosi).", "operationId": "searchUnified", "tags": ["Search"], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query. Supports state prefix (e.g., CA:pelosi)", "example": "healthcare" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50 }, "description": "Results per category" } ], "responses": { "200": { "description": "Search results across all domains", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedSearchResponse" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/search/policy-area": { "get": { "summary": "Policy area search", "description": "Cross-domain search by policy area: bills, regulations, spending, and committees.", "operationId": "searchPolicyArea", "tags": ["Search"], "parameters": [ { "name": "policyArea", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Policy area name", "example": "Health" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 }, "description": "Results per category" } ], "responses": { "200": { "description": "Policy area results", "content": { "application/json": { "schema": { "type": "object", "properties": { "policyArea": { "type": "string" }, "bills": { "type": "array", "items": { "type": "object" } }, "billsTotal": { "type": "integer", "nullable": true, "description": "Every bill (hr, s, hjres, sjres) CRS filed under this policy area in billsCongress; bills holds at most `limit`. Null when the bill corpus is unavailable." }, "billsCongress": { "type": "integer", "nullable": true }, "regulations": { "type": "array", "items": { "type": "object" } }, "spending": { "type": "object", "nullable": true }, "committees": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/geocode": { "get": { "summary": "Reverse-geocode coordinates to district", "description": "Coordinate-based convenience endpoint. Resolves `lat`/`lng` query parameters to the congressional district via Census. For address resolution, use POST.", "operationId": "geocodeCoordinates", "tags": ["Districts"], "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Latitude (WGS84 decimal degrees)", "example": 38.8977 }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Longitude (WGS84 decimal degrees)", "example": -77.0365 } ], "responses": { "200": { "description": "District resolved from coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeError" } } } }, "404": { "description": "No result for this address or these coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeError" } } } } } }, "post": { "summary": "Geocode address", "description": "Resolve a street address to congressional district and representatives.", "operationId": "geocodeAddress", "tags": ["Districts"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["address", "coordinates"], "default": "address" }, "address": { "type": "string", "example": "1600 Pennsylvania Ave, Washington DC" }, "latitude": { "type": "number" }, "longitude": { "type": "number" } } } } } }, "responses": { "200": { "description": "Geocoded district and representatives", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeError" } } } } } } }, "/districts/all": { "get": { "summary": "List all districts", "description": "List all 435 congressional districts with demographics, political data, and representatives.", "operationId": "listAllDistricts", "tags": ["Districts"], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 435 }, "description": "Results per page" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "All districts", "content": { "application/json": { "schema": { "type": "object", "properties": { "districts": { "type": "array", "items": { "$ref": "#/components/schemas/DistrictDetail" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" }, "districts": { "type": "array", "items": {}, "description": "Always empty on error" } }, "required": ["error"] } } } } } } }, "/representatives/all": { "get": { "summary": "List all representatives", "description": "List all 535 current members of Congress.", "operationId": "listAllRepresentatives", "tags": ["Representatives"], "parameters": [ { "name": "chamber", "in": "query", "schema": { "type": "string", "enum": ["house", "senate"] } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "party", "in": "query", "schema": { "type": "string", "enum": ["D", "R", "I"] } } ], "responses": { "200": { "description": "All representatives", "content": { "application/json": { "schema": { "type": "object", "properties": { "representatives": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentativeSummary" } }, "metadata": { "type": "object" } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ApiServiceUnavailable" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/representative/{bioguideId}": { "get": { "summary": "Full representative profile", "description": "Comprehensive profile with biography, committees, social media, contact info, and leadership roles.", "operationId": "getFullRepresentativeProfile", "tags": ["Representatives"], "parameters": [ { "name": "bioguideId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bioguide ID", "example": "P000197" } ], "responses": { "200": { "description": "Full representative profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "representative": { "$ref": "#/components/schemas/RepresentativeDetail" }, "profile": { "type": "object" }, "committees": { "type": "array", "items": { "type": "object" } }, "biography": { "type": "object", "nullable": true }, "socialMedia": { "type": "object", "nullable": true }, "identifiers": { "type": "object" }, "metadata": { "type": "object" } } } } } }, "404": { "description": "Representative not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepresentativeErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "description": "Upstream data source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepresentativeErrorEnvelope" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepresentativeErrorEnvelope" } } } } } } }, "/compare": { "get": { "summary": "Compare one legislator (one side of a comparison)", "description": "One side of a side-by-side comparison: roll-call totals and party alignment from chamber baselines, plus current-Congress and career sponsored / enacted / cosponsored counts from the record-card rollup. Call once per legislator. Sections that cannot be computed are null, never zero. Campaign finance is served by /representative/{bioguideId}/finance.", "operationId": "compareLegislators", "tags": ["Representatives"], "parameters": [ { "name": "bioguideId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z][0-9]{6}$" }, "description": "Bioguide ID of one legislator (a letter followed by six digits)", "example": "P000197" } ], "responses": { "200": { "description": "Comparison data", "content": { "application/json": { "schema": { "type": "object", "properties": { "bioguideId": { "type": "string" }, "chamber": { "type": "string", "enum": ["House", "Senate"] }, "congress": { "type": "integer" }, "votingRecord": { "type": "object", "nullable": true, "description": "null when chamber baselines are unavailable for this member.", "properties": { "totalVotes": { "type": "integer", "description": "Yea + Nay + Present across the analyzed roll calls" }, "appearances": { "type": "integer" }, "missedPct": { "type": "number" }, "partyLoyaltyScore": { "type": "number", "nullable": true, "description": "Party-majority alignment 0-100; null below the vote floor or for independents" }, "rollCallsAnalyzed": { "type": "integer" }, "fullCoverage": { "type": "boolean" }, "dataAsOf": { "type": "string" } } }, "effectiveness": { "type": "object", "nullable": true, "description": "null when the legislation rollup could not be built.", "properties": { "current": { "type": "object", "properties": { "billsSponsored": { "type": "integer" }, "billsEnacted": { "type": "integer" }, "billsCosponsored": { "type": "integer" } } }, "career": { "type": "object", "properties": { "billsSponsored": { "type": "integer" }, "billsEnacted": { "type": "integer" }, "billsCosponsored": { "type": "integer" } } }, "billsCosponsoredIsLowerBound": { "type": "boolean", "description": "True when current.billsCosponsored is a floor, not a count" }, "committeeMemberships": { "type": "integer", "nullable": true }, "dataAsOf": { "type": "string" } } }, "methodology": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" }, "404": { "$ref": "#/components/responses/ApiNotFound" } } } }, "/state-legislature/{state}": { "get": { "summary": "State legislature", "description": "List state legislators for a given state via OpenStates.", "operationId": "getStateLegislature", "tags": ["States"], "parameters": [ { "name": "state", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "Two-letter state code", "example": "MI" }, { "name": "chamber", "in": "query", "schema": { "type": "string", "enum": ["upper", "lower"] }, "description": "Filter by chamber (upper = Senate, lower = House/Assembly)" }, { "name": "party", "in": "query", "schema": { "type": "string" }, "description": "Filter by party" } ], "responses": { "200": { "description": "State legislators", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "stateName": { "type": "string" }, "legislators": { "type": "array", "items": { "type": "object" } }, "totalCount": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/state-bills/{state}": { "get": { "summary": "State bills", "description": "Search and list state legislation via OpenStates.", "operationId": "getStateBills", "tags": ["States"], "parameters": [ { "name": "state", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "Two-letter state code", "example": "MI" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Keyword search" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by bill status" }, { "name": "chamber", "in": "query", "schema": { "type": "string", "enum": ["upper", "lower"] }, "description": "Filter by chamber" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "Results per page" } ], "responses": { "200": { "description": "State bills", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "stateName": { "type": "string" }, "bills": { "type": "array", "items": { "type": "object" } }, "totalCount": { "type": "integer" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/state-legislators-by-address": { "get": { "summary": "State legislators by address (query form)", "description": "Query-parameter convenience for POST. Accepts street/city/state/zip as query params and proxies to the same handler.", "operationId": "getStateLegislatorsByAddressQuery", "tags": ["States"], "parameters": [ { "name": "street", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Street address line" }, { "name": "city", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter state abbreviation (e.g., CA, NY)" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional ZIP code to assist geocoding" } ], "responses": { "200": { "description": "State legislators for address", "content": { "application/json": { "schema": { "type": "object", "properties": { "legislators": { "type": "array", "items": { "type": "object" } }, "district": { "type": "object" } } } } } }, "400": { "description": "Invalid or unparseable address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLookupError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "description": "Address, district, or legislators not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLookupError" } } } }, "502": { "description": "Upstream geocoder or Open States error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLookupError" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLookupError" } } } } } }, "post": { "summary": "State legislators by address", "description": "Look up state legislators for a street address via OpenStates geocoding.", "operationId": "getStateLegislatorsByAddress", "tags": ["States"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } }, "required": ["street", "city", "state"] } } } }, "responses": { "200": { "description": "State legislators for address", "content": { "application/json": { "schema": { "type": "object", "properties": { "legislators": { "type": "array", "items": { "type": "object" } }, "district": { "type": "object" } } } } } }, "400": { "description": "Invalid or unparseable address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLookupError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "description": "Address, district, or legislators not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLookupError" } } } }, "502": { "description": "Upstream geocoder or Open States error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLookupError" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLookupError" } } } } } } }, "/graph/neighbors/{nodeId}": { "get": { "summary": "Graph neighbors", "description": "Get connected entities in the civic knowledge graph. Supports filtering by edge type, confidence, and temporal range.", "operationId": "getGraphNeighbors", "tags": ["Graph"], "parameters": [ { "name": "nodeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Node ID in format type:identifier (e.g., rep:P000197, bill:119-hr-1)", "example": "rep:P000197" }, { "name": "edgeTypes", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated edge types to include" }, { "name": "minConfidence", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Minimum confidence threshold (0-1)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "Maximum edges to return" } ], "responses": { "200": { "description": "Graph neighbors", "content": { "application/json": { "schema": { "type": "object", "properties": { "center": { "type": "object" }, "edges": { "type": "array", "items": { "type": "object" } }, "connectedNodes": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/mesh/entity/{nodeId}": { "get": { "summary": "Mesh entity", "description": "Unified entity resolver. Returns identity, neighborhood, intelligence, and temporal context for any civic entity.", "operationId": "getMeshEntity", "tags": ["Graph"], "parameters": [ { "name": "nodeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Entity ID in format type:identifier (e.g., rep:P000197)", "example": "rep:P000197" } ], "responses": { "200": { "description": "Full entity with context", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/mesh/temporal/{nodeId}": { "get": { "summary": "Temporal profile", "description": "Quarterly time-series of edge activity and trends for an entity.", "operationId": "getMeshTemporal", "tags": ["Graph"], "parameters": [ { "name": "nodeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Entity ID", "example": "rep:P000197" }, { "name": "quarters", "in": "query", "schema": { "type": "integer", "default": 8, "minimum": 1, "maximum": 20 }, "description": "Number of quarters to include" } ], "responses": { "200": { "description": "Temporal profile", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/mesh/embed/{type}/{id}": { "get": { "summary": "Embeddable widget", "description": "Returns self-contained HTML for iframe embedding. Supports scorecard and district widget types.", "operationId": "getMeshEmbed", "tags": ["Widgets"], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["scorecard", "district"] }, "description": "Widget type" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Entity ID (bioguideId for scorecard, districtId for district)", "example": "P000197" } ], "responses": { "200": { "description": "Self-contained HTML widget", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ApiBadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ApiInternalError" } } } }, "/feed/member/{bioguideId}": { "get": { "summary": "Member activity feed", "description": "Atom feed of a legislator's voting activity, committee assignments, and sponsored bills.", "operationId": "getMemberFeed", "tags": ["Feeds"], "parameters": [ { "name": "bioguideId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bioguide ID", "example": "P000197" } ], "responses": { "200": { "description": "Atom XML feed", "content": { "application/atom+xml": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/FeedInternalError" } } } }, "/feed/district/{districtId}": { "get": { "summary": "District activity feed", "description": "Atom feed of legislative activity affecting a congressional district.", "operationId": "getDistrictFeed", "tags": ["Feeds"], "parameters": [ { "name": "districtId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "District ID (e.g., MI-12)", "example": "MI-12" } ], "responses": { "200": { "description": "Atom XML feed", "content": { "application/atom+xml": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/FeedInternalError" } } } }, "/feed/bills/latest": { "get": { "summary": "Latest bills feed", "description": "Atom feed of recently introduced or updated bills in Congress.", "operationId": "getLatestBillsFeed", "tags": ["Feeds"], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Number of bills" } ], "responses": { "200": { "description": "Atom XML feed", "content": { "application/atom+xml": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/FeedInternalError" } } } }, "/feed/bill/{billId}": { "get": { "summary": "Bill lifecycle feed", "description": "Atom feed of status updates and actions for a specific bill.", "operationId": "getBillFeed", "tags": ["Feeds"], "parameters": [ { "name": "billId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bill ID", "example": "119-hr-1" } ], "responses": { "200": { "description": "Atom XML feed", "content": { "application/atom+xml": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/FeedInternalError" } } } }, "/feed/committee/{committeeId}": { "get": { "summary": "Committee feed", "description": "Atom feed of committee meetings, reports, and member updates.", "operationId": "getCommitteeFeed", "tags": ["Feeds"], "parameters": [ { "name": "committeeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Committee system code", "example": "HSJU" } ], "responses": { "200": { "description": "Atom XML feed", "content": { "application/atom+xml": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/FeedInternalError" } } } } }, "components": { "schemas": { "Meta": { "type": "object", "properties": { "apiVersion": { "type": "string", "example": "v1" }, "timestamp": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "license": { "type": "string", "example": "MIT" }, "documentation": { "type": "string", "format": "uri" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Advisory notes about the request, such as unrecognized query parameters that were ignored. Omitted when there is nothing to report." } }, "required": ["apiVersion", "timestamp"] }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": ["total", "limit", "offset", "hasMore"] }, "V1Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "details": { "type": "string" } }, "required": ["code", "message"] }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "IntelligenceMetadata": { "type": "object", "description": "Common metadata for all intelligence insights", "properties": { "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score (0-1)" }, "dataAsOf": { "type": "string", "format": "date-time", "description": "Data freshness timestamp" }, "methodology": { "type": "string", "description": "How the analysis was computed" }, "disclaimer": { "type": "string", "description": "Correlation/causation disclaimer" } }, "required": ["confidence", "dataAsOf", "methodology", "disclaimer"] }, "RepresentativeSummary": { "type": "object", "properties": { "bioguideId": { "type": "string", "example": "P000197" }, "name": { "type": "string", "example": "Nancy Pelosi" }, "party": { "type": "string", "enum": ["D", "R", "I"] }, "state": { "type": "string", "example": "CA" }, "district": { "type": "string", "nullable": true }, "chamber": { "type": "string", "enum": ["House", "Senate"] }, "title": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "yearsInOffice": { "type": "number", "nullable": true }, "nextElection": { "type": "string", "nullable": true } }, "required": ["bioguideId", "name", "party", "state", "chamber", "title"] }, "RepresentativeDetail": { "type": "object", "properties": { "bioguideId": { "type": "string" }, "name": { "type": "string" }, "party": { "type": "string" }, "state": { "type": "string" }, "district": { "type": "string", "nullable": true }, "chamber": { "type": "string" }, "title": { "type": "string" }, "isHistorical": { "type": "boolean" }, "votingMember": { "type": "boolean" }, "role": { "type": "string" }, "bio": { "type": "string", "nullable": true }, "currentTerm": { "type": "object", "nullable": true }, "socialMedia": { "type": "object", "nullable": true }, "contact": { "type": "object", "nullable": true }, "committees": { "type": "array", "items": { "type": "object" } }, "leadershipRoles": { "type": "array", "items": { "type": "object" } }, "yearsInOffice": { "type": "number", "nullable": true }, "nextElection": { "type": "string", "nullable": true } }, "required": ["bioguideId", "name", "party", "state", "chamber"] }, "BillSummary": { "type": "object", "properties": { "congress": { "type": "integer" }, "number": { "type": "string" }, "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "originChamber": { "type": "string", "nullable": true }, "updateDate": { "type": "string", "nullable": true }, "latestAction": { "type": "object", "nullable": true, "properties": { "actionDate": { "type": "string" }, "text": { "type": "string" } } }, "url": { "type": "string" } }, "required": ["congress", "number", "url"] }, "BillDetail": { "type": "object", "properties": { "billId": { "type": "string" }, "congress": { "type": "integer" }, "type": { "type": "string" }, "number": { "type": "string" }, "title": { "type": "string" }, "shortTitle": { "type": "string", "nullable": true }, "originChamber": { "type": "string" }, "introducedDate": { "type": "string" }, "updateDate": { "type": "string", "nullable": true }, "latestAction": { "type": "object", "nullable": true }, "policyArea": { "type": "string", "nullable": true }, "sponsors": { "type": "array", "items": { "type": "object", "properties": { "bioguideId": { "type": "string" }, "fullName": { "type": "string" }, "party": { "type": "string" }, "state": { "type": "string" } } } }, "cosponsorsCount": { "type": "integer" }, "committeesCount": { "type": "integer" }, "actionsCount": { "type": "integer" }, "textVersionsCount": { "type": "integer" }, "url": { "type": "string" } }, "required": ["billId", "congress", "type", "number", "title"] }, "BillAISummary": { "type": "object", "properties": { "billId": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "whatItDoes": { "type": "string" }, "whyItMatters": { "type": "string" }, "keyPoints": { "type": "array", "items": { "type": "string" } }, "whoItAffects": { "type": "array", "items": { "type": "string" } }, "readingLevel": { "type": "string" }, "confidence": { "type": "number" }, "lastUpdated": { "type": "string", "format": "date-time" }, "source": { "type": "string" } }, "required": ["billId", "title", "summary"] }, "VoteDetail": { "type": "object", "properties": { "voteId": { "type": "string" }, "chamber": { "type": "string" }, "congress": { "type": "integer" }, "rollNumber": { "type": "integer" }, "question": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "result": { "type": "string", "nullable": true }, "date": { "type": "string", "nullable": true }, "time": { "type": "string", "nullable": true }, "totals": { "type": "object", "properties": { "yea": { "type": "integer" }, "nay": { "type": "integer" }, "present": { "type": "integer" }, "notVoting": { "type": "integer" } } }, "positions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "party": { "type": "string" }, "state": { "type": "string" }, "vote": { "type": "string" }, "bioguideId": { "type": "string" } } } }, "url": { "type": "string" } }, "required": ["voteId", "chamber", "congress", "rollNumber"] }, "DistrictDetail": { "type": "object", "properties": { "districtId": { "type": "string", "example": "MI-12" }, "state": { "type": "string" }, "district": { "type": "string" }, "label": { "type": "string" }, "representatives": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentativeSummary" } } }, "required": ["districtId", "state", "district", "representatives"] }, "CommitteeSummary": { "type": "object", "properties": { "systemCode": { "type": "string" }, "name": { "type": "string" }, "chamber": { "type": "string" }, "type": { "type": "string", "nullable": true }, "url": { "type": "string" } }, "required": ["systemCode", "name", "chamber"] }, "CommitteeDetail": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "chamber": { "type": "string" }, "type": { "type": "string", "nullable": true }, "jurisdiction": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "chair": { "type": "object", "nullable": true }, "rankingMember": { "type": "object", "nullable": true }, "members": { "type": "array", "items": { "type": "object" } }, "subcommittees": { "type": "array", "items": { "type": "object" } }, "lastUpdated": { "type": "string", "format": "date-time" } }, "required": ["id", "name", "chamber"] }, "IndexResponse": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "endpoints": { "type": "object" }, "feeds": { "type": "object" }, "rateLimit": { "type": "object" }, "links": { "type": "object" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "RepresentativeListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentativeSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "RepresentativeDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RepresentativeDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "BillListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "BillDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "BillSummaryResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillAISummary" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "VoteDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VoteDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "DistrictDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DistrictDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CommitteeListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommitteeSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CommitteeDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommitteeDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ChangelogResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "currentVersion": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "date": { "type": "string", "format": "date" }, "changes": { "type": "array", "items": { "type": "string" } } } } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "IntelligenceInsightResponse": { "description": "Standard intelligence analyzer response", "allOf": [ { "$ref": "#/components/schemas/IntelligenceMetadata" } ] }, "SectorLeaderboardResponse": { "type": "object", "properties": { "sector": { "type": "string" }, "legislators": { "type": "array", "items": { "type": "object", "properties": { "bioguideId": { "type": "string" }, "name": { "type": "string" }, "party": { "type": "string" }, "state": { "type": "string" }, "totalFromSector": { "type": "number" }, "percentOfTotal": { "type": "number" } } } }, "metadata": { "type": "object" } } }, "MoneyReportResponse": { "type": "object", "properties": { "state": { "type": "string" }, "district": { "type": "string" }, "representatives": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentativeSummary" } }, "aggregates": { "type": "object" }, "narrative": { "type": "string" }, "confidence": { "type": "number" }, "dataAsOf": { "type": "string", "format": "date-time" }, "accuracyNote": { "type": "string", "description": "Present on ZIP-based GET responses. ZIP ↔ district alignment is 10–20% wrong; use the address POST endpoint for authoritative results." }, "status": { "type": "string", "enum": ["complete", "partial", "unavailable"], "description": "'partial' when accuracyNote is set (ZIP input); 'complete' for address input." }, "dataQuality": { "$ref": "#/components/schemas/DataQuality" }, "sourceStatus": { "type": "array", "items": { "$ref": "#/components/schemas/SourceStatus" } } } }, "GeocodeResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "district": { "type": "string" }, "representatives": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentativeSummary" } }, "stateLegislators": { "type": "array", "items": { "type": "object" } }, "stateInfo": { "type": "object" }, "geocoded": { "type": "object" }, "accuracyNote": { "type": "string", "description": "Present when the request carried a ZIP code (body.zipCode) rather than pure coordinates or address-only. Downstream consumers using the returned district inherit ZIP imprecision (10–20% misalignment)." }, "isMultiDistrict": { "type": "boolean" }, "dataQuality": { "$ref": "#/components/schemas/DataQuality" }, "sourceStatus": { "type": "array", "items": { "$ref": "#/components/schemas/SourceStatus" } } } }, "UnifiedSearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "totalResults": { "type": "integer" }, "representatives": { "type": "array", "items": { "type": "object" } }, "bills": { "type": "array", "items": { "type": "object" } }, "committees": { "type": "array", "items": { "type": "object" } }, "stateLegislators": { "type": "array", "items": { "type": "object" } }, "stateBills": { "type": "array", "items": { "type": "object" } } } }, "AnalyticsResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "object", "required": [ "dateRange", "totalRequests", "endpointCount", "endpoints" ], "properties": { "dateRange": { "type": "object", "required": ["start", "end"], "properties": { "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" } } }, "totalRequests": { "type": "integer", "minimum": 0 }, "endpointCount": { "type": "integer", "minimum": 0 }, "endpoints": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Map of endpoint path → request count" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "DataQuality": { "type": "string", "enum": ["complete", "partial", "empty", "unavailable"], "description": "Backbone data-quality signal. 'complete' = all sources healthy and input authoritative; 'partial' = approximate input (e.g. ZIP-based lookup) or a degraded/failed sub-source; 'empty' = sources healthy but no data exists; 'unavailable' = upstream failure." }, "SourceStatus": { "type": "object", "description": "Per-upstream-source fetch status, so consumers can distinguish \"no data exists\" from \"upstream failed\".", "properties": { "source": { "type": "string", "example": "census-geocoder" }, "status": { "type": "string", "enum": ["ok", "error", "timeout", "rate-limited", "not-configured"] }, "errorMessage": { "type": "string" }, "fetchedAt": { "type": "string", "format": "date-time" } }, "required": ["source", "status", "fetchedAt"] }, "ApiError": { "type": "object", "description": "Error envelope returned by non-v1 /api endpoints (intelligence, search, geocode, mesh). v1 endpoints use V1Error.", "properties": { "success": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "VALIDATION_ERROR", "INTERNAL_ERROR", "UNAUTHORIZED", "FORBIDDEN", "RATE_LIMITED", "SERVICE_UNAVAILABLE", "BAD_REQUEST", "NO_DATA" ], "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "string", "description": "Optional technical detail" } }, "required": ["code", "message"] }, "metadata": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" } } } }, "required": ["success", "error"] }, "JsonRpcError": { "type": "object", "description": "JSON-RPC 2.0 error envelope returned by the MCP endpoint.", "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] }, "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "JSON-RPC error code (e.g. -32000)" }, "message": { "type": "string" } }, "required": ["code", "message"] }, "id": { "description": "Request id the error responds to; null for transport-level errors." } }, "required": ["jsonrpc", "error"] }, "GeocodeError": { "type": "object", "description": "Error envelope returned by /geocode.", "properties": { "success": { "type": "boolean", "enum": [false] }, "error": { "type": "string", "description": "Human-readable error message" } }, "required": ["success", "error"] }, "AddressLookupError": { "type": "object", "description": "Error envelope returned by /state-legislators-by-address.", "properties": { "error": { "type": "string", "description": "Machine-readable error type (e.g. INVALID_ADDRESS, ADDRESS_NOT_FOUND, CENSUS_API_ERROR, OPENSTATES_API_ERROR, UNKNOWN_ERROR)" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": ["error", "message"] }, "RepresentativeErrorEnvelope": { "type": "object", "description": "Error envelope returned by /representative/{bioguideId}.", "properties": { "representative": { "description": "Always null on error." }, "success": { "type": "boolean", "enum": [false] }, "error": { "type": "string", "description": "Human-readable error message" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": ["success", "error"] } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Operator bearer token (CACHE_WARM_SECRET). Required for internal observability endpoints under /v1." } }, "responses": { "BadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "Unauthorized": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "BadGateway": { "description": "Upstream data source error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "ServiceUnavailable": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "TooManyRequests": { "description": "Rate limit exceeded (60 requests/minute per IP)", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests per window (IETF RateLimit headers)" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in current window" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Quota policy, e.g. '60;w=60' (60 requests per 60s window)" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy: maximum requests per window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy: remaining requests in current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy: Unix millisecond timestamp when the window resets" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "ApiBadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ApiNotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ApiServiceUnavailable": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "InternalServerError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Error" } } } }, "ApiInternalError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "FeedInternalError": { "description": "Unexpected server error (Atom error document)", "content": { "application/atom+xml": { "schema": { "type": "string", "description": "XML error document" } } } } } }, "tags": [ { "name": "Index", "description": "API discovery and versioning" }, { "name": "Representatives", "description": "Members of Congress — federal level" }, { "name": "Bills", "description": "Legislation and AI summaries" }, { "name": "Votes", "description": "Roll-call votes" }, { "name": "Districts", "description": "Congressional districts and geocoding" }, { "name": "Committees", "description": "Congressional committees" }, { "name": "Intelligence", "description": "ML-powered analysis — vote prediction, influence chains, temporal shifts" }, { "name": "Search", "description": "Cross-domain search" }, { "name": "States", "description": "State legislators and bills via OpenStates" }, { "name": "Graph", "description": "Civic knowledge graph — entity resolution and connections" }, { "name": "Feeds", "description": "Atom XML feeds for subscriptions" }, { "name": "Widgets", "description": "Embeddable HTML widgets for iframe embedding" }, { "name": "MCP", "description": "Model Context Protocol for AI assistants" }, { "name": "Analytics", "description": "Operational observability endpoints (authenticated)" } ] }