{"openapi":"3.1.0","info":{"title":"CongressInvests API","description":"\n**Real-time congressional stock trade disclosures** from the U.S. Senate and House of Representatives, refreshed every 6 hours.\n\n## Quick start\n\n```bash\ncurl https://congressinfor-production.up.railway.app/trades/NVDA\n```\n\n## Authentication\n\n| Tier | Header | Daily limit |\n|------|--------|-------------|\n| Free | *(none required)* | 100 req / day per IP |\n| Pro  | `X-Api-Key: YOUR_KEY` | 50,000 req / day |\n\nExceeding the free limit returns **HTTP 429 Too Many Requests**.\n\n## Data freshness\n\nEvery response includes three freshness fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `last_updated` | string (ISO 8601 UTC) | Timestamp of the last successful cache load |\n| `data_lag_minutes` | integer | Minutes elapsed since the last refresh |\n| `next_refresh_in_minutes` | integer | Minutes until the next scheduled refresh |\n\n## SDKs & examples\n\nOfficial Python and Node.js SDKs are available in the\n[congressinvests-api](https://github.com/Dianadone/congressinvests-api) repository.\n","contact":{"name":"CongressInvests Support","url":"https://congressinfor-production.up.railway.app/#contact"},"version":"1.0.0"},"paths":{"/status":{"get":{"tags":["Meta"],"summary":"Health","description":"Liveness check plus cache status and data freshness metadata.\n\nReturns `status: \"ok\"` when the API is up. The `ready` field indicates\nwhether the trade cache has finished its initial load. Use `data_lag_minutes`\nand `next_refresh_in_minutes` to understand how fresh the data is.","operationId":"health_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["Meta"],"summary":"Health","description":"Liveness check plus cache status and data freshness metadata.\n\nReturns `status: \"ok\"` when the API is up. The `ready` field indicates\nwhether the trade cache has finished its initial load. Use `data_lag_minutes`\nand `next_refresh_in_minutes` to understand how fresh the data is.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/trades/recent":{"get":{"tags":["Trades"],"summary":"Get Recent Trades","description":"The most recently filed trades across all tickers, sorted by filing date descending.","operationId":"get_recent_trades_trades_recent_get","parameters":[{"name":"chamber","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by chamber: Senate or House","title":"Chamber"},"description":"Filter by chamber: Senate or House"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":365,"minimum":1},{"type":"null"}],"description":"Only include trades filed within the last N days","title":"Days"},"description":"Only include trades filed within the last N days"},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/trades/{ticker}":{"get":{"tags":["Trades"],"summary":"Get Trades","description":"All trades for a specific stock ticker, sorted by filing date descending.\n\n- Case-insensitive: `nvda` and `NVDA` both work.\n- Filter by `chamber=Senate` or `chamber=House`.\n- Paginate with `offset` and `limit` (max 500).\n- Covers the last 365 days of disclosures from both chambers.\n- Free tier: 100 requests/day per IP. Pro: 50,000/day with `X-Api-Key`.","operationId":"get_trades_trades__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"chamber","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by chamber: Senate or House","title":"Chamber"},"description":"Filter by chamber: Senate or House"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/trades/{ticker}/summary":{"get":{"tags":["Trades"],"summary":"Get Trade Summary","description":"AI trend analysis for a ticker based on congressional trade disclosures.\n\nReturns the same trade payload as ``/trades/{ticker}`` plus an ``ai_analysis`` key:\n\n- **sentiment** – \"bullish\", \"bearish\", or \"mixed\" (derived from buy/sell ratio)\n- **summary** – 2–3 sentence narrative of the trading trend\n- **notable_patterns** – any notable clustering, divergence, or concentration in the data\n- **stats** – objective counts computed server-side (total, buys, sells, unique members, date range)\n\nAnalysis is grounded strictly in the disclosed filing data — no speculation about the company.\nReturns HTTP 503 if the ANTHROPIC_API_KEY environment variable is not set.\nRequires a valid Pro API key — returns HTTP 401 for unauthenticated requests.","operationId":"get_trade_summary_trades__ticker__summary_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"chamber","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by chamber: Senate or House","title":"Chamber"},"description":"Filter by chamber: Senate or House"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/trades":{"get":{"tags":["Trades"],"summary":"Get All Trades","description":"All cached trades across every ticker, sorted by transaction date descending.\n\nUse this for a global feed or bulk analysis. Default limit is 200; max is 1000.\nFilter by `chamber=Senate` or `chamber=House`. Paginate with `offset`.","operationId":"get_all_trades_trades_get","parameters":[{"name":"chamber","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by chamber: Senate or House","title":"Chamber"},"description":"Filter by chamber: Senate or House"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cache/status":{"get":{"tags":["Meta"],"summary":"Cache Status","description":"Cache metadata: readiness, age, ticker counts per chamber.","operationId":"cache_status_cache_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/cache/refresh":{"post":{"tags":["Admin"],"summary":"Cache Refresh","description":"Force a full cache reload. Requires a valid X-Api-Key header.","operationId":"cache_refresh_cache_refresh_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stripe/checkout":{"post":{"tags":["Meta"],"summary":"Stripe Checkout","description":"Create a Stripe Checkout session for the Pro plan. Returns a redirect URL.","operationId":"stripe_checkout_stripe_checkout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/stripe/portal":{"post":{"tags":["Meta"],"summary":"Stripe Portal","description":"Create a Stripe Billing Portal session for an existing Pro subscriber.\nPass the subscriber's API key in the X-Api-Key header.\nReturns a redirect URL to manage or cancel the subscription.","operationId":"stripe_portal_stripe_portal_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stripe/webhook":{"post":{"tags":["Meta"],"summary":"Stripe Webhook","description":"Stripe webhook handler — processes subscription lifecycle events.","operationId":"stripe_webhook_stripe_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/contact":{"post":{"tags":["Meta"],"summary":"Contact","description":"Save a contact form submission to the SQLite database.","operationId":"contact_contact_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/subscribe":{"post":{"tags":["Webhooks"],"summary":"Webhook Subscribe","description":"Subscribe to trade alerts. Requires a valid Pro API key.\nAt least one of `ticker` or `politician` must be provided.\n`events` accepts: \"buy\", \"sell\", \"any\" (default: [\"any\"]).","operationId":"webhook_subscribe_webhooks_subscribe_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/unsubscribe/{sub_id}":{"delete":{"tags":["Webhooks"],"summary":"Webhook Unsubscribe","description":"Delete a webhook subscription by its ID. Must use the same API key used to create it.","operationId":"webhook_unsubscribe_webhooks_unsubscribe__sub_id__delete","parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"string","title":"Sub Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/my-subscriptions":{"get":{"tags":["Webhooks"],"summary":"Webhook List","description":"List all webhook subscriptions for the authenticated API key.","operationId":"webhook_list_webhooks_my_subscriptions_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ContactRequest":{"properties":{"name":{"type":"string","title":"Name"},"email":{"type":"string","format":"email","title":"Email"},"plan":{"type":"string","title":"Plan","default":""},"message":{"type":"string","title":"Message"}},"type":"object","required":["name","email","message"],"title":"ContactRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SubscribeRequest":{"properties":{"webhook_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Webhook Url"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"politician":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Politician"},"events":{"items":{"type":"string"},"type":"array","title":"Events","default":["any"]}},"type":"object","required":["webhook_url"],"title":"SubscribeRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"Trades","description":"Query congressional stock trade disclosures by ticker, date range, or chamber. Free tier: 100 req/day per IP, no key required."},{"name":"Webhooks","description":"**Pro tier only.** Subscribe to real-time trade alerts by ticker or politician. Requires a valid `X-Api-Key` header."},{"name":"Meta","description":"Health checks, cache status, and contact form."},{"name":"Admin","description":"Cache management endpoints. Require a valid `X-Api-Key` header."}]}