{ "openapi": "3.1.0", "info": { "title": "GovGreed Public API v1", "version": "1.0.0", "summary": "REST API for the GovGreed civic accountability dataset.", "description": "Read-only API for the integrated US civic accountability graph: 218M FEC contributions, 190K STOCK Act trades, 62K bills, 156 indexed tables. Free tier 20 calls/day per key. Paid tiers (Founders / Pro / Institutional) 750 calls/day. 5 req/sec burst limit. RFC 7807 errors. Docs: https://www.govgreed.com/docs", "contact": { "name": "GovGreed", "email": "info@govgreed.com", "url": "https://www.govgreed.com/docs" }, "license": { "name": "CC BY 4.0 (data) / MIT (code)", "url": "https://creativecommons.org/licenses/by/4.0/" } }, "servers": [ { "url": "https://www.govgreed.com/api/v1", "description": "Production gateway" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "gg_pub_... API key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Authorization: Bearer gg_pub_..." } }, "schemas": { "Envelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "description": "Endpoint-specific payload (object, array, or scalar)." }, "meta": { "type": "object", "properties": { "version": { "type": "string", "example": "v1" }, "request_id": { "type": "string", "example": "req_abc123def4" }, "count": { "type": "integer" }, "tier": { "type": "string", "enum": [ "free", "pro" ], "description": "free = 20 calls/day. pro = 750 calls/day (Founders, Pro, Institutional all share this quota). Founders ($24.50/mo locked forever) and Pro ($49/mo) are the public tiers." }, "quota": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "reset_at": { "type": "string", "format": "date-time" } } } } } } }, "Problem": { "type": "object", "description": "RFC 7807 problem+json error", "required": [ "status", "code" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } }, "Trade": { "type": "object", "description": "One STOCK Act disclosure row (returned by /trades and its scoped variants). Field names and types are stable under /api/v1 — read these literal keys, no defensive aliasing needed.", "properties": { "trade_id": { "type": "integer", "format": "int64", "description": "Stable unique id for this disclosure row" }, "bioguide_id": { "type": "string", "example": "P000197", "description": "Politician join key (resolve names via /politicians/search)" }, "politician_name": { "type": "string", "example": "Nancy Pelosi" }, "party": { "type": "string", "example": "D" }, "state": { "type": "string", "example": "CA" }, "chamber": { "type": "string", "enum": [ "House", "Senate" ] }, "ticker": { "type": "string", "nullable": true, "example": "NVDA", "description": "Null for non-ticker assets (real estate, expiring options)" }, "transaction_type": { "type": "string", "example": "Purchase", "description": "Raw STOCK Act type: Purchase / Sale / Sale (Partial) / Exchange / Receive / etc. This is the canonical key (not 'type' or 'side')." }, "trade_date": { "type": "string", "format": "date", "description": "Date the trade occurred" }, "filed_date": { "type": "string", "format": "date", "description": "Date the disclosure was filed. The since/until filters and default ordering use THIS field. Canonical key (not 'disclosure_date')." }, "amount_range": { "type": "string", "example": "$1,001 - $15,000", "description": "Original SEC amount bucket" }, "amount_min": { "type": "number", "description": "Parsed lower bound (USD)" }, "amount_max": { "type": "number", "nullable": true, "description": "Parsed upper bound (USD)" }, "asset_class": { "type": "string", "nullable": true, "example": "stock", "description": "stock / option / bond / etf / crypto / other. Canonical key (not 'asset_type')." }, "disclosure_gap_days": { "type": "integer", "description": "filed_date minus trade_date, in days. > 45 = late under the STOCK Act. (~99% populated.)" }, "owner": { "type": "string", "nullable": true, "description": "Trade owner: Self / Spouse / Joint / Child / Dependent. SPARSE — populated on only ~1% of rows (newer disclosures). Treat absence as unknown, not 'Self'." }, "jurisdiction": { "type": "object", "nullable": true, "description": "Present ONLY with ?expand=jurisdiction (Founders/Pro). Whether the member sits on a committee whose sector covers this ticker — the 'trading in their own lane' tag.", "properties": { "in_committee_sector": { "type": "boolean" }, "sector": { "type": "string", "nullable": true }, "committees": { "type": "array", "items": { "type": "string" } } } }, "related_bills": { "type": "array", "nullable": true, "description": "Present ONLY with ?expand=bills (Founders/Pro). Bills this specific trade correlates to (top 5 by correlation score). Empty for ~97% of trades; when present it is the stronger 'handling THIS bill' signal.", "items": { "type": "object", "properties": { "bill_number": { "type": "string", "example": "HR.2670" }, "title": { "type": "string" }, "tier": { "type": "string", "description": "Correlation tier (S/A+/A/...)" }, "days_between": { "type": "integer", "description": "Days between the bill action and the trade" }, "is_sponsor": { "type": "boolean" }, "is_cosponsor": { "type": "boolean" }, "role": { "type": "string", "nullable": true, "description": "Member's committee role on the bill, if any" } } } } } }, "Signal": { "type": "object", "properties": { "signal_id": { "type": "integer" }, "ticker": { "type": "string" }, "politician_name": { "type": "string" }, "politician_bioguide_id": { "type": "string" }, "politician_party": { "type": "string" }, "politician_state": { "type": "string" }, "direction": { "type": "string" }, "trade_date": { "type": "string", "format": "date" }, "master_score": { "type": "number" }, "master_tier": { "type": "string" }, "convergence_type": { "type": "string" }, "active_signals": { "type": "array", "items": { "type": "string" } }, "signal_count": { "type": "integer" }, "freshness_label": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "contested": { "type": "boolean" } } }, "Prediction": { "type": "object", "properties": { "id": { "type": "integer" }, "prediction_date": { "type": "string", "format": "date" }, "committee_code": { "type": "string" }, "committee_name": { "type": "string" }, "markup_meeting_date": { "type": "string", "format": "date-time" }, "markup_event_id": { "type": "string" }, "days_until_markup": { "type": "integer" }, "politician_bioguide_id": { "type": "string" }, "politician_name": { "type": "string" }, "politician_party": { "type": "string" }, "committee_role": { "type": "string" }, "predicted_ticker": { "type": "string" }, "predicted_sector": { "type": "string" }, "predicted_direction": { "type": "string" }, "confidence_score": { "type": "number" }, "prediction_tier": { "type": "string" }, "historical_frequency": { "type": "number" }, "committee_alignment": { "type": "number" }, "contribution_pattern": { "type": "number" }, "lobbying_pattern": { "type": "number" }, "politician_quality": { "type": "number" }, "position_size": { "type": "number" }, "timing_pattern": { "type": "number" }, "reasoning": { "type": "object" }, "status": { "type": "string" }, "was_correct": { "type": "boolean" }, "actual_trade_id": { "type": "integer" }, "actual_ticker": { "type": "string" }, "actual_trade_date": { "type": "string", "format": "date" } } }, "SectorSummary": { "type": "object", "properties": { "sector": { "type": "string" }, "company_count": { "type": "integer" }, "trades_in_window": { "type": "integer" }, "has_positioning": { "type": "boolean" } } }, "Markup": { "type": "object", "properties": { "event_id": { "type": "string" }, "committee_code": { "type": "string" }, "committee_name": { "type": "string" }, "meeting_date": { "type": "string", "format": "date-time" }, "days_away": { "type": "integer" }, "bill_number": { "type": "string" }, "bill_title": { "type": "string" }, "investability_score": { "type": "number" }, "is_hot": { "type": "boolean" }, "committee_traders": { "type": "integer" } } }, "BillCarveout": { "type": "object", "properties": { "section": { "type": "string" }, "amount_text": { "type": "string" }, "amount_usd": { "type": "number" }, "recipient": { "type": "string" }, "ticker": { "type": "string" }, "company_name": { "type": "string" }, "sector": { "type": "string" }, "is_named_company": { "type": "boolean" }, "confidence": { "type": "number" }, "purpose": { "type": "string" } } }, "TickerCarveout": { "type": "object", "properties": { "bill_number": { "type": "string" }, "congress": { "type": "integer" }, "section": { "type": "string" }, "recipient": { "type": "string" }, "amount_usd": { "type": "number" }, "amount_text": { "type": "string" }, "purpose": { "type": "string" }, "is_named_company": { "type": "boolean" }, "confidence": { "type": "number" }, "evidence_quote": { "type": "string" }, "extracted_by_model": { "type": "string" }, "extracted_at": { "type": "string", "format": "date-time" }, "bill_id": { "type": "integer" }, "duplicate_count": { "type": "integer" } } }, "AtlasEntry": { "type": "object", "properties": { "table_name": { "type": "string" }, "domain": { "type": "string" }, "tier": { "type": "integer" }, "purpose": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "rpcs_used_by": { "type": "array", "items": { "type": "string" } }, "pages_used_by": { "type": "array", "items": { "type": "string" } }, "catalog_doc": { "type": "string" }, "notes": { "type": "string" }, "is_canonical": { "type": "boolean" }, "last_reviewed": { "type": "string", "format": "date" }, "rows_estimated": { "type": "integer" }, "size_bytes": { "type": "integer" }, "size_pretty": { "type": "string" }, "total_reads": { "type": "integer" }, "inserts_lifetime": { "type": "integer" } } }, "MacroSeries": { "type": "object", "properties": { "series_id": { "type": "string" }, "series_name": { "type": "string" }, "observation_date": { "type": "string", "format": "date" }, "value": { "type": "number" }, "frequency": { "type": "string" }, "units": { "type": "string" } } }, "GovernmentContract": { "type": "object", "properties": { "award_id": { "type": "string" }, "recipient_name": { "type": "string" }, "recipient_ticker": { "type": "string" }, "award_amount": { "type": "number" }, "awarding_agency": { "type": "string" }, "awarding_sub_agency": { "type": "string" }, "naics_code": { "type": "string" }, "naics_description": { "type": "string" }, "sector": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "performance_location": { "type": "string" } } }, "PoliticianDonor": { "type": "object", "properties": { "donor_name": { "type": "string" }, "donor_employer": { "type": "string" }, "donor_occupation": { "type": "string" }, "donor_state": { "type": "string" }, "total_to_this_pol": { "type": "number" }, "gift_count": { "type": "integer" }, "last_gift": { "type": "string", "format": "date" }, "donor_lifetime": { "type": "number" }, "donor_unique_recipients": { "type": "integer" } } }, "VesselEvent": { "type": "object", "properties": { "mmsi": { "type": "integer" }, "ship_name": { "type": "string" }, "ship_type_name": { "type": "string" }, "chokepoint": { "type": "string" }, "flag_country": { "type": "string" }, "destination": { "type": "string" }, "draught": { "type": "number" }, "sog": { "type": "number" }, "cog": { "type": "number" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "observed_at": { "type": "string", "format": "date-time" } } }, "WhaleOpportunity": { "type": "object", "properties": { "bill_number": { "type": "string" }, "bill_title": { "type": "string" }, "bill_stage": { "type": "string" }, "pass_likelihood": { "type": "integer" }, "ticker": { "type": "string" }, "company_name": { "type": "string" }, "market_cap": { "type": "number" }, "impact_ratio": { "type": "number" }, "est_revenue_impact": { "type": "number" }, "insider_tier": { "type": "string" }, "insider_score": { "type": "integer" }, "insider_cluster": { "type": "integer" }, "insider_ceo_cfo": { "type": "integer" }, "ev_score": { "type": "number" } } }, "DonorSearchResult": { "type": "object", "properties": { "name_lc": { "type": "string" }, "name_display": { "type": "string" }, "employer_display": { "type": "string" }, "occupation_display": { "type": "string" }, "state_display": { "type": "string" }, "total_dollars": { "type": "number" }, "contribution_count": { "type": "integer" }, "total_2026": { "type": "number" }, "similarity": { "type": "number" } } }, "DonorFingerprint": { "type": "object", "properties": { "donor_lc": { "type": "string" }, "donor_display": { "type": "string" }, "state_display": { "type": "string" }, "employer_display": { "type": "string" }, "total_dollars": { "type": "number" }, "contribution_count": { "type": "integer" }, "variants_merged": { "type": "array", "items": { "type": "string" } }, "variant_count": { "type": "integer" }, "match_method": { "type": "string" }, "match_confidence": { "type": "number" } } }, "EmployerSearchResult": { "type": "object", "properties": { "employer_lc": { "type": "string" }, "employer_display": { "type": "string" }, "contribution_count": { "type": "integer" }, "unique_donors": { "type": "integer" }, "total_dollars": { "type": "number" }, "total_2024": { "type": "number" }, "total_2026": { "type": "number" }, "similarity": { "type": "number" } } }, "FaraRegistrant": { "type": "object", "properties": { "registration_number": { "type": "integer" }, "name": { "type": "string" }, "business_name": { "type": "string" }, "address_1": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "registration_date": { "type": "string", "format": "date" }, "termination_date": { "type": "string", "format": "date" }, "is_active": { "type": "boolean" } } }, "Nomination": { "type": "object", "properties": { "congress": { "type": "integer" }, "number": { "type": "integer" }, "citation": { "type": "string" }, "description": { "type": "string" }, "organization": { "type": "string" }, "nomination_type": { "type": "string" }, "is_civilian": { "type": "boolean" }, "received_date": { "type": "string", "format": "date" }, "latest_action_text": { "type": "string" }, "latest_action_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "vote_yeas": { "type": "integer" }, "vote_nays": { "type": "integer" }, "url": { "type": "string" } } }, "Nonprofit": { "type": "object", "properties": { "ein": { "type": "string" }, "strein": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "subsection_code": { "type": "integer" }, "subsection_label": { "type": "string" }, "revenue_amount": { "type": "number" }, "asset_amount": { "type": "number" }, "is_politically_active": { "type": "boolean" }, "similarity": { "type": "number" } } }, "OgeOfficial": { "type": "object", "properties": { "department_slug": { "type": "string" }, "position_code": { "type": "string" }, "position_title": { "type": "string" }, "department": { "type": "string" }, "category": { "type": "string" }, "rank": { "type": "integer" }, "holder_name": { "type": "string" }, "holder_since": { "type": "string", "format": "date" }, "oge_filer_id": { "type": "string" }, "is_active": { "type": "boolean" }, "photo_url": { "type": "string" }, "filing_count": { "type": "integer" } } }, "PoliticianSearchResult": { "type": "object", "properties": { "bioguide_id": { "type": "string" }, "name": { "type": "string" }, "party": { "type": "string" }, "state": { "type": "string" }, "chamber": { "type": "string" }, "district": { "type": "string" }, "in_office": { "type": "boolean" }, "greediness_score": { "type": "number" }, "trade_count_6mo": { "type": "integer" }, "similarity": { "type": "number" } } } }, "responses": { "Ok": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "TradesOk": { "description": "Success — data is an array of Trade rows, ordered by filed_date descending", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } } } } ] } } } }, "BadRequest": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "Auth failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "Rate limited", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "SignalList": { "description": "Success — array of Signal", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } } } } ] } } } }, "PredictionList": { "description": "Success — array of Prediction", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Prediction" } } } } ] } } } }, "SectorSummaryList": { "description": "Success — array of SectorSummary", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SectorSummary" } } } } ] } } } }, "MarkupList": { "description": "Success — array of Markup", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Markup" } } } } ] } } } }, "BillCarveoutList": { "description": "Success — array of BillCarveout", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillCarveout" } } } } ] } } } }, "TickerCarveoutList": { "description": "Success — array of TickerCarveout", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TickerCarveout" } } } } ] } } } }, "AtlasEntryList": { "description": "Success — array of AtlasEntry", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AtlasEntry" } } } } ] } } } }, "MacroSeriesList": { "description": "Success — array of MacroSeries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MacroSeries" } } } } ] } } } }, "GovernmentContractList": { "description": "Success — array of GovernmentContract", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GovernmentContract" } } } } ] } } } }, "PoliticianDonorList": { "description": "Success — array of PoliticianDonor", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoliticianDonor" } } } } ] } } } }, "VesselEventList": { "description": "Success — array of VesselEvent", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VesselEvent" } } } } ] } } } }, "WhaleOpportunityList": { "description": "Success — array of WhaleOpportunity", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhaleOpportunity" } } } } ] } } } }, "DonorSearchResultList": { "description": "Success — array of DonorSearchResult", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DonorSearchResult" } } } } ] } } } }, "DonorFingerprintList": { "description": "Success — array of DonorFingerprint", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DonorFingerprint" } } } } ] } } } }, "EmployerSearchResultList": { "description": "Success — array of EmployerSearchResult", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmployerSearchResult" } } } } ] } } } }, "FaraRegistrantList": { "description": "Success — array of FaraRegistrant", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FaraRegistrant" } } } } ] } } } }, "NominationList": { "description": "Success — array of Nomination", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Nomination" } } } } ] } } } }, "NonprofitList": { "description": "Success — array of Nonprofit", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Nonprofit" } } } } ] } } } }, "OgeOfficialList": { "description": "Success — array of OgeOfficial", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OgeOfficial" } } } } ] } } } }, "PoliticianSearchResultList": { "description": "Success — array of PoliticianSearchResult", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoliticianSearchResult" } } } } ] } } } }, "DonorSearchList": { "description": "Success — donor results (shape varies by fingerprint param)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DonorSearchResult" }, { "$ref": "#/components/schemas/DonorFingerprint" } ] } } } } ] } } } } } }, "tags": [ { "name": "Meta", "description": "Health, atlas, OpenAPI" }, { "name": "Donors", "description": "FEC individual contributors" }, { "name": "Employers", "description": "FEC employer aggregates" }, { "name": "Politicians", "description": "Sitting members of Congress" }, { "name": "Bills", "description": "US federal bills" }, { "name": "Companies", "description": "Public companies (tickers)" }, { "name": "Signals", "description": "Composite trade signals + herd convergence" }, { "name": "Predictions", "description": "Forward-looking trade predictions + EV-ranked opportunities" }, { "name": "Sectors", "description": "Sector-level congressional flow + positioning" }, { "name": "Nominations", "description": "Senate confirmation tracker (Trump cabinet + judicial)" }, { "name": "Nonprofits", "description": "501(c)(3/4/5/6/19) + 527 organizations" }, { "name": "Contracts", "description": "Federal contracts (USASpending)" }, { "name": "Government", "description": "Federal equity stakes / loans / grants" }, { "name": "OGE", "description": "Executive branch financial disclosures (cabinet conflicts)" }, { "name": "FARA", "description": "Foreign Agents Registration Act" }, { "name": "Macro", "description": "FRED (Federal Reserve) + EIA (Energy) indicators" }, { "name": "Markets", "description": "Kalshi prediction markets with BPI overlay" }, { "name": "Vessels", "description": "AIS chokepoint vessel events" }, { "name": "Districts", "description": "Census ACS congressional district demographics" }, { "name": "Account", "description": "Your API key + usage" } ], "paths": { "/market/context": { "get": { "tags": [ "Market" ], "operationId": "getMarketContext", "security": [], "summary": "AI-native market context — self-describing bundle (every field carries methodology + limitation)", "description": "Honest, sourced market context for a ticker that is never a naked number: quote, 52-week range position, volume-vs-10d-average, free float, corporate insider sentiment (MSPR), analyst consensus, and macro backdrop — each field stamped with its own `methodology` and `limitation`. Layered on top: GovGreed's proprietary `govgreed_signals` (congressional buys/sells with conviction buckets, the 7-layer signal tier, Form 4 insider signal, political-influence breakdown, bill exposure). Public/free callers get the commodity context plus a teaser (signal tier + congressional counts); the full moat requires a Founders/Pro API key. Deliberately excludes manipulation-bait (no order-book/Level-2, no volume-to-direction inference). Context, not a recommendation; not an execution feed. Cached ~5 minutes.", "parameters": [ { "name": "ticker", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 10 } }, { "name": "days", "in": "query", "required": false, "description": "Corporate-insider signal lookback window (full moat, paid only).", "schema": { "type": "integer", "default": 90, "minimum": 7, "maximum": 365 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/status": { "get": { "tags": [ "Meta" ], "operationId": "getStatus", "security": [], "summary": "Health check (no auth)", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/openapi": { "get": { "tags": [ "Meta" ], "operationId": "getOpenapi", "security": [], "summary": "This OpenAPI 3.1 document", "responses": { "200": { "description": "OpenAPI document", "content": { "application/json": {} } } } } }, "/endpoints": { "get": { "tags": ["Meta"], "operationId": "getEndpoints", "security": [], "summary": "Self-discovery map — every endpoint, live", "description": "Machine-readable list of every endpoint (method, path, summary, tags, params, auth), generated from this spec. Public (no key) so a client can orient on first contact. meta.schema_version is a content hash of the OpenAPI — poll this map daily and re-fetch /openapi.json whenever schema_version changes (the surface evolves as we ship; same self-updating contract as the GovGreed MCP server). One discovery poll/day is covered by the quota allowance.", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/atlas": { "get": { "tags": [ "Meta" ], "operationId": "getAtlas", "summary": "Full data catalog — START HERE for AI agents and integrations", "description": "Returns every queryable table with row count, current status (live/deprecated/empty), upstream source, RPCs that read it, frontend pages that consume it, last-reviewed date, and dedup verdicts. Recommended first call for any AI agent integrating this API — use it to discover what exists before composing chained queries to entity-specific endpoints.", "responses": { "200": { "$ref": "#/components/responses/AtlasEntryList" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/atlas/{table}": { "get": { "tags": [ "Meta" ], "operationId": "getAtlasOne", "summary": "Atlas entry for one table", "parameters": [ { "name": "table", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/AtlasEntryList" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/donors/search": { "get": { "tags": [ "Donors" ], "operationId": "searchDonors", "summary": "Fuzzy-search FEC individual donors", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Donor name (any format)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "aggregate", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fingerprint", "raw" ], "default": "fingerprint" }, "description": "fingerprint = one row per real-world person (FEC name variants merged, with variants_merged audit array). raw = one row per name string as filed." } ], "responses": { "200": { "$ref": "#/components/responses/DonorSearchList" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/donors/{name}/profile": { "get": { "tags": [ "Donors" ], "operationId": "getDonorProfile", "summary": "Full profile for one donor", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Exact name_display from search_donors (URL-encoded)" } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/employers/search": { "get": { "tags": [ "Employers" ], "operationId": "searchEmployers", "summary": "Fuzzy-search FEC employers", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/EmployerSearchResultList" } } } }, "/employers/{name}/profile": { "get": { "tags": [ "Employers" ], "operationId": "getEmployerProfile", "summary": "Full firm profile", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/politicians/{bioguide_id}": { "get": { "tags": [ "Politicians" ], "operationId": "getPolitician", "summary": "One politician's identity", "parameters": [ { "name": "bioguide_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]\\d{6}$" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/politicians/{bioguide_id}/donors": { "get": { "tags": [ "Politicians" ], "operationId": "getPoliticianDonors", "summary": "Donors who funded a politician", "parameters": [ { "name": "bioguide_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]\\d{6}$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/PoliticianDonorList" } } } }, "/bills/{bill_number}": { "get": { "tags": [ "Bills" ], "operationId": "getBill", "summary": "Full bill intelligence", "description": "bill_number is NOT unique across Congresses — every Congress recycles the same numbering. Defaults to the current (119th) Congress. Pass ?congress= for historical lookups. /bills/{n} and /bills/{n}/pass-likelihood share this default so they always reference the same bill.", "parameters": [ { "name": "bill_number", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Dotted form: HR.4521, S.5, HJRES.7" }, { "name": "congress", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 117, 118, 119 ], "default": 119 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/bills/{bill_number}/pass-likelihood": { "get": { "tags": [ "Bills" ], "operationId": "getBillPassLikelihood", "summary": "Deterministic 0-100 pass probability", "parameters": [ { "name": "bill_number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "congress", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 117, 118, 119 ] } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/companies/{ticker}": { "get": { "tags": [ "Companies" ], "operationId": "getCompany", "summary": "Public-ticker metadata", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 10 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/companies/{ticker}/political-influence": { "get": { "tags": [ "Companies" ], "operationId": "getCompanyPoliticalInfluence", "summary": "0-100 political influence score", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 10 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/companies/{ticker}/insider-signal": { "get": { "tags": [ "Companies" ], "operationId": "getCompanyInsiderSignal", "summary": "Form 4 insider signal — open-market buys + executive comp (awards/exercises)", "description": "Returns two classes of insider activity: (1) open-market buys with score 0–100, signal_tier (S/A+/A/B/C/F), cluster detection, top 10 recent buys; (2) executive comp — award_count, award_total_value (stock grants valued at market price on grant date), exercise_count, exercise_total_value, recent_awards array. For defense primes (LMT, RTX, NOC, GD, BA) where execs receive stock as comp rather than buying open-market, the awards/exercises panel is the real signal. Use days=180 for full annual-cycle awards view.", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 10 } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 90, "minimum": 7, "maximum": 365 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/companies/{ticker}/carveouts": { "get": { "tags": [ "Companies" ], "operationId": "getCompanyCarveouts", "summary": "Bill carveouts targeting one ticker (deduplicated server-side)", "description": "All bill_carveouts rows for a ticker, deduplicated on (bill_number, purpose, recipient). Highest-confidence LLM extraction wins per dedup key. Returns canonical list with duplicate_count showing how many raw extractions agreed. Example: LMT returns 8 canonical carveouts ~$9B (F-35 $4.3B, Sikorsky $3.6B, UH-60 $630M, Apache $504M).", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 10 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/TickerCarveoutList" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/companies/{ticker}/llm-analysis": { "get": { "tags": [ "Companies" ], "operationId": "getCompanyLlmAnalysis", "summary": "LLM iron-triangle profile per ticker", "description": "Government_dependence, regulatory_density, lobbying_intensity scores + congressional_champions/critics + key_legislation_to_watch + regulatory_threats/opportunities. The narrative version of political-risk for a ticker.", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 10 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/politicians/{bioguide_id}/profile": { "get": { "tags": [ "Politicians" ], "operationId": "getPoliticianProfile", "summary": "Full LLM iron-triangle profile (45+ fields)", "description": "Conflict-of-interest summary, predicted_corruption_risk, top_donor_industries, sector_specializations, watchlist_signals, signature_legislation, expected_next_action, vulnerability_signal, forecast_thesis, recommended_watchlist_tickers.", "parameters": [ { "name": "bioguide_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]\\d{6}$" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/politicians/{bioguide_id}/conflict-score": { "get": { "tags": [ "Politicians" ], "operationId": "getPoliticianConflictScore", "summary": "Integer conflict score (0-100) + breakdowns", "description": "538 politicians pre-scored. Includes trade_activity, late_filing, committee_alignment, donor_alignment, voted_holdings sub-scores. Sub-100ms point lookup.", "parameters": [ { "name": "bioguide_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]\\d{6}$" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/bills/{bill_number}/carveouts": { "get": { "tags": [ "Bills" ], "operationId": "getBillCarveouts", "summary": "LLM-extracted line-item earmarks per bill", "description": "10K+ extracted carveouts across all bills. Returns section, dollar amount, recipient, ticker, sector, confidence, purpose. The follow-the-pork endpoint.", "parameters": [ { "name": "bill_number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "congress", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 117, 118, 119 ], "default": 119 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "$ref": "#/components/responses/BillCarveoutList" } } } }, "/bills/{bill_number}/timeline": { "get": { "tags": [ "Bills" ], "operationId": "getBillTimeline", "summary": "Unified bill event stream — state transitions + congressional + Form 4 + markups", "parameters": [ { "name": "bill_number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "congress", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 117, 118, 119 ], "default": 119 } }, { "name": "max_trades", "in": "query", "required": false, "schema": { "type": "integer", "default": 200, "maximum": 500 } }, { "name": "min_impact_ratio", "in": "query", "required": false, "schema": { "type": "number", "default": 0.02 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/politicians/search": { "get": { "tags": [ "Politicians" ], "operationId": "searchPoliticians", "summary": "Fuzzy politician search by name", "description": "Returns up to 100 matches ranked by trigram similarity then greediness. Use bioguide_id from result for follow-up calls (you don't have to know that P000197 = Pelosi anymore).", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/PoliticianSearchResultList" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/politicians/{bioguide_id}/committees": { "get": { "tags": [ "Politicians" ], "operationId": "getPoliticianCommittees", "summary": "Active committee assignments", "description": "Returns all active committee + subcommittee memberships with role (Chair / Ranking / Member). Useful for understanding informational edge from committee position.", "parameters": [ { "name": "bioguide_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]\\d{6}$" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/bills/{bill_number}/votes": { "get": { "tags": [ "Bills" ], "operationId": "getBillVotes", "summary": "Roll call votes on a bill (tally + per-member positions)", "description": "Returns each roll call with chamber, date, question, result, tally (yea/nay/present/not_voting), and per-member positions ordered by party then name.", "parameters": [ { "name": "bill_number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "congress", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 117, 118, 119 ], "default": 119 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/signals/top": { "get": { "tags": [ "Signals" ], "operationId": "getSignalsTop", "summary": "Top-ranked composite trade signals", "description": "Flagship signal product. 7-layer fusion (politician quality, herd, bill correlation, technical, sector, contribution, lobbying). A+ tier has 72.7% backtested win rate. Filter by minimum tier.", "parameters": [ { "name": "tier", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "S", "A+", "A", "B", "C", "D", "F" ], "default": "B" }, "description": "Minimum tier" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Only return freshness-flagged signals (last 30 days)" } ], "responses": { "200": { "$ref": "#/components/responses/SignalList" } } } }, "/herd-signals": { "get": { "tags": [ "Signals" ], "operationId": "getHerdSignals", "summary": "3+ politicians converging on the same ticker", "description": "Detected herd events: when N=3+ politicians buy/sell the same ticker within a tight window. Returns ticker, politician_count, herd_score, herd_tier, net_direction, committee_alignment_pct.", "parameters": [ { "name": "tier", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "S", "A+", "A", "B", "C", "D", "F" ] } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 90, "maximum": 365 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/predictions/top": { "get": { "tags": [ "Predictions" ], "operationId": "getPredictionsTop", "summary": "Top active forward-looking trade predictions", "description": "Output of the 4 prediction engines (committee markup / pattern / signal-bridge / bill-correlation). Default returns ACTIVE A-tier+. ~819 active predictions across ~76 politicians.", "parameters": [ { "name": "tier", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "S", "A+", "A", "B", "C", "D", "F" ], "default": "A" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "DARK_WINDOW", "CONFIRMED", "MISSED", "EXPIRED" ], "default": "ACTIVE" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/PredictionList" } } } }, "/whale-opportunities": { "get": { "tags": [ "Predictions" ], "operationId": "getWhaleOpportunities", "summary": "EV-ranked bills (pass% × impact_ratio × insider tier)", "description": "Triple-confirmation alpha screen: bills with high pass probability + material market impact + corporate insider buying. Insider multiplier: S=2.0, A+=1.6, A=1.4, B=1.2, C=1.05.", "parameters": [ { "name": "congress", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 117, 118, 119 ], "default": 119 } }, { "name": "min_pass_pct", "in": "query", "required": false, "schema": { "type": "integer", "default": 40, "minimum": 0, "maximum": 100 } }, { "name": "min_impact_ratio", "in": "query", "required": false, "schema": { "type": "number", "default": 0.05 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/WhaleOpportunityList" } } } }, "/sectors/{sector}/positioning": { "get": { "tags": [ "Sectors" ], "operationId": "getSectorPositioning", "summary": "Congressional buy/sell flow per sector over N days", "description": "Summary stats + top 10 politicians by volume + top 10 tickers by trade count. Sector match is case-insensitive against companies.sector. Call GET /sectors first to discover valid sector names — guessing names like 'pharma' or 'materials' returns 404.", "parameters": [ { "name": "sector", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 365 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sectors": { "get": { "tags": [ "Sectors" ], "operationId": "listSectors", "summary": "List valid sector names for positioning queries", "description": "The valid vocabulary for /sectors/{sector}/positioning, with per-sector company counts and congressional trade counts in the window. has_positioning=false means positioning currently returns 404 for that sector. Call this before guessing sector names.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 365 }, "description": "Trade-count window in days" } ], "responses": { "200": { "$ref": "#/components/responses/SectorSummaryList" } } } }, "/trades": { "get": { "tags": [ "Trades" ], "operationId": "listTrades", "summary": "Raw STOCK Act congressional trade disclosures", "description": "The core dataset: every STOCK Act disclosure (190K+ rows, 5-year history, synced daily). Each row carries politician name/party/state/chamber, ticker, transaction type, trade + filed dates, amount range, asset class, and disclosure_gap_days (>45 = late under the STOCK Act). Ordered by filed_date descending. Page with limit/offset.", "parameters": [ { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact ticker filter (e.g. NVDA)" }, { "name": "politician", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bioguide ID filter (e.g. P000197). Resolve names via /politicians/search" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "filed_date >= (YYYY-MM-DD)" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "filed_date <= (YYYY-MM-DD)" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "purchase", "sale" ] }, "description": "Transaction-type prefix filter" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated enrichments (Founders/Pro only): jurisdiction, bills. e.g. expand=jurisdiction,bills" } ], "responses": { "200": { "$ref": "#/components/responses/TradesOk" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/politicians/{bioguide_id}/trades": { "get": { "tags": [ "Trades", "Politicians" ], "operationId": "getPoliticianTrades", "summary": "STOCK Act disclosures for one politician", "description": "Same shape and filters as /trades, scoped to one bioguide_id.", "parameters": [ { "name": "bioguide_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z][0-9]{6}$" } }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "purchase", "sale" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated enrichments (Founders/Pro only): jurisdiction, bills" } ], "responses": { "200": { "$ref": "#/components/responses/TradesOk" } } } }, "/companies/{ticker}/trades": { "get": { "tags": [ "Trades", "Companies" ], "operationId": "getCompanyTrades", "summary": "STOCK Act disclosures for one ticker", "description": "Same shape and filters as /trades, scoped to one ticker. 404 if the ticker is not tracked.", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "politician", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "purchase", "sale" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated enrichments (Founders/Pro only): jurisdiction, bills" } ], "responses": { "200": { "$ref": "#/components/responses/TradesOk" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/markups/upcoming": { "get": { "tags": [ "Bills", "Committees" ], "operationId": "getUpcomingMarkups", "summary": "Upcoming committee markup calendar", "description": "Scheduled committee markups for the next N days — the catalyst calendar. Each row carries committee, meeting date, days_away, linked bill (when known), normalized 0-100 investability score, and committee_traders (how many committee members trade in the affected sector).", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 120 }, "description": "Look-ahead window" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "$ref": "#/components/responses/MarkupList" } } } }, "/nominations/search": { "get": { "tags": [ "Nominations" ], "operationId": "searchNominations", "summary": "Search Senate nominations", "description": "Trump cabinet + judicial confirmations (6,727 across 117/118/119). Filter by status, congress, or fuzzy text on description/organization/citation.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "congress", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 117, 118, 119 ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/NominationList" } } } }, "/nominations/{congress}/{number}": { "get": { "tags": [ "Nominations" ], "operationId": "getNomination", "summary": "One Senate nomination by (congress, number)", "parameters": [ { "name": "congress", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/nonprofits/search": { "get": { "tags": [ "Nonprofits" ], "operationId": "searchNonprofits", "summary": "Search 40K nonprofits (ProPublica)", "description": "501(c)(3/4/5/6/19) + 527. Subsection 4 = dark-money tracker. Filter by subsection, state, or political_only flag.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } }, { "name": "subsection", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 3, 4, 5, 6, 19, 527 ] } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2 } }, { "name": "political", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/NonprofitList" } } } }, "/nonprofits/{ein}": { "get": { "tags": [ "Nonprofits" ], "operationId": "getNonprofitProfile", "summary": "Full Form 990 profile by EIN", "parameters": [ { "name": "ein", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{2}-?\\d{7}$" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/government-contracts": { "get": { "tags": [ "Contracts" ], "operationId": "getGovernmentContracts", "summary": "Federal contracts (USASpending)", "parameters": [ { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 10 } }, { "name": "agency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "min_amount", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "$ref": "#/components/responses/GovernmentContractList" } } } }, "/companies/{ticker}/contracts": { "get": { "tags": [ "Companies" ], "operationId": "getCompanyContracts", "summary": "Federal contracts for one ticker", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 10 } }, { "name": "agency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "min_amount", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "$ref": "#/components/responses/GovernmentContractList" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/government-equity-stakes": { "get": { "tags": [ "Government" ], "operationId": "getGovernmentEquityStakes", "summary": "Federal equity / loan / grant deals INTO public companies", "description": "Trump-era 'government as VC' asset class. Intel CHIPS, MP DoD $400M, USAR Commerce, GE Vernova LPO, Plug Power. Includes price reaction (t+1, t+30, return_30d_pct).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/oge/officials": { "get": { "tags": [ "OGE" ], "operationId": "searchOgeOfficials", "summary": "Search Trump cabinet + senior White House staff", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "responses": { "200": { "$ref": "#/components/responses/OgeOfficialList" } } } }, "/oge/officials/{department_slug}": { "get": { "tags": [ "OGE" ], "operationId": "getOgeOfficialProfile", "summary": "OGE financial-disclosure profile per cabinet official", "description": "Identity + filings + top 25 holdings (by value) + conflict flags (critical mineral / defense / pharma / crypto exposure).", "parameters": [ { "name": "department_slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/companies/{ticker}/forecast": { "get": { "tags": [ "Companies" ], "operationId": "getCompanyForecast", "summary": "LLM 30-day politician trade forecast for a ticker", "description": "Forecasts include catalyst bill, expected position size range, historical precedent, concurrent corroborating signals. Coverage: 13 tickers (defense + select tech) as of 2026-04-30.", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 10 } }, { "name": "days_ahead", "in": "query", "required": false, "schema": { "type": "integer", "default": 60, "maximum": 365 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/fara/registrants/search": { "get": { "tags": [ "FARA" ], "operationId": "searchFaraRegistrants", "summary": "Search FARA primary registrants", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "$ref": "#/components/responses/FaraRegistrantList" } } } }, "/macro/fred": { "get": { "tags": [ "Macro" ], "operationId": "getMacroFred", "summary": "FRED macro time series", "description": "17 series (DFF/GS2/GS10/GS30/CPI/PCE/UNRATE/GDP/VIX/etc) 2012-now. Pass series= comma-separated to filter.", "parameters": [ { "name": "series", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated series IDs" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200, "maximum": 1000 } } ], "responses": { "200": { "$ref": "#/components/responses/MacroSeriesList" } } } }, "/macro/eia": { "get": { "tags": [ "Macro" ], "operationId": "getMacroEia", "summary": "EIA petroleum / energy time series (weekly)", "parameters": [ { "name": "series", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200, "maximum": 1000 } } ], "responses": { "200": { "$ref": "#/components/responses/MacroSeriesList" } } } }, "/markets/kalshi": { "get": { "tags": [ "Markets" ], "operationId": "getMarketsKalshi", "summary": "Live Kalshi prediction markets with BPI overlay", "description": "For bill-linked markets, returns our bpi_score + edge_pp + signal_side alongside Kalshi market_implied_pct. Filter by category or minimum |edge_pp|.", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "min_edge", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/vessels/chokepoints": { "get": { "tags": [ "Vessels" ], "operationId": "getVesselsChokepoints", "summary": "AIS vessel events at maritime chokepoints (Hormuz / Malacca / etc)", "parameters": [ { "name": "chokepoint", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 365 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "$ref": "#/components/responses/VesselEventList" } } } }, "/districts/{state}/{district}/demographics": { "get": { "tags": [ "Districts" ], "operationId": "getDistrictDemographics", "summary": "Census ACS demographics for one congressional district", "parameters": [ { "name": "state", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "district", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Your API key metadata", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/me/usage": { "get": { "tags": [ "Account" ], "operationId": "getMeUsage", "summary": "Daily usage timeline", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 90 } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } } } }