{"openapi":"3.1.0","info":{"title":"AI Analytics — public-data hub","version":"0.1.0","description":"Structured public US government data (SEC EDGAR, FDA, more coming) delivered in a shape AI crawlers can consume cheaply. All endpoints currently free; section-body fetches are logged with a shadow price ($0.001/section) in preparation for Cloudflare Pay Per Crawl.","contact":{"email":"info@ai-analytics.org"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://api.ai-analytics.org","description":"Production"},{"url":"https://api.ai-analytics.org","description":"Current host"}],"tags":[{"name":"discovery","description":"Topics, stats, search, feed, today, openapi, sitemap, agencies"},{"name":"sec.companies","description":"SEC filers by CIK or ticker; profiles, summaries"},{"name":"sec.insider","description":"Form 4 insider transactions + leaderboards"},{"name":"sec.holdings","description":"13F institutional holdings"},{"name":"sec.financials","description":"XBRL financial facts + comparisons"},{"name":"sec.sections","description":"Per-URL filing section bodies (shadow-billable)"},{"name":"fda.recalls","description":"FDA drug/device/food enforcement actions"},{"name":"fda.adverse","description":"FAERS drug adverse-event reports"},{"name":"fda.510k","description":"FDA medical device 510(k) clearances"},{"name":"contracts","description":"Federal contract awards (schema live; ingest pending)"},{"name":"register","description":"Federal Register documents (rules, exec orders, notices)"},{"name":"weather","description":"NOAA active hazard alerts"},{"name":"climate","description":"USGS earthquake events"},{"name":"sec.funds","description":"NPORT-P mutual fund metadata"}],"paths":{"/api/v1/topics":{"get":{"tags":["discovery"],"summary":"List all data topics with status, counts, latest date, and example endpoints","responses":{"200":{"description":"OK"}}}},"/api/v1/stats":{"get":{"tags":["discovery"],"summary":"Comprehensive aggregate counts across all topics + pay-per-crawl shadow ledger","responses":{"200":{"description":"summary, documents_by_topic, sec_filings_by_form, sections_by_doc_type, pay_per_crawl_shadow_ledger"}}}},"/api/v1/agencies":{"get":{"tags":["discovery"],"summary":"Cross-source entities: SEC industries (by SIC), FDA firms, FR agencies","parameters":[{"name":"source","in":"query","schema":{"type":"string","enum":["sec","fda","register"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/":{"get":{"tags":["discovery"],"summary":"Landing — live counts + active topics + endpoint catalog","responses":{"200":{"description":"OK"}}}},"/api/v1/sec/filings/recent":{"get":{"tags":["sec.companies"],"summary":"Generic SEC filing search — by form_type, family, ticker, cik, days","parameters":[{"name":"form_type","in":"query","schema":{"type":"string"},"example":"8-K"},{"name":"family","in":"query","schema":{"type":"string","enum":["annual","quarterly","current","insider","holdings","proxy","registration","other"]}},{"name":"ticker","in":"query","schema":{"type":"string"}},{"name":"cik","in":"query","schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","default":7,"maximum":365}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":1000}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/search":{"get":{"tags":["discovery"],"summary":"Full-text search across all section bodies (BM25)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"topic","in":"query","schema":{"type":"string","enum":["sec","fda"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":200}}],"responses":{"200":{"description":"Matched sections with BM25 rank + <mark> snippets"}}}},"/feed.json":{"get":{"tags":["discovery"],"summary":"JSON Feed v1.1 of recent filings/recalls (poll for what's new)","parameters":[{"name":"topic","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"application/feed+json"}}}},"/today.json":{"get":{"tags":["discovery"],"summary":"Cross-topic daily pulse — top insider sells/buys, new filings, FDA recalls, adverse events, 510(k)s","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":7,"maximum":30}}],"responses":{"200":{"description":"OK — one envelope with sec.* and fda.* sub-objects"}}}},"/sitemap.xml":{"get":{"tags":["discovery"],"summary":"Sitemap index (links to paginated /sitemap-N.xml pages of section URLs)","responses":{"200":{"description":"OK"}}}},"/api/v1/sec/funds/recent":{"get":{"tags":["sec.holdings"],"summary":"Recent NPORT-P mutual fund filings (fund-level metadata)","parameters":[{"name":"min_net_assets","in":"query","schema":{"type":"number"}},{"name":"period","in":"query","schema":{"type":"string","format":"date"}},{"name":"registrant","in":"query","schema":{"type":"string","description":"Substring match on fund family name"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/weather/alerts/active":{"get":{"tags":["weather"],"summary":"Active NOAA/NWS weather alerts","parameters":[{"name":"severity","in":"query","schema":{"type":"string","enum":["Extreme","Severe","Moderate","Minor"]}},{"name":"event","in":"query","schema":{"type":"string","description":"Substring filter on event type (e.g., Tornado, Flood)"}},{"name":"state","in":"query","schema":{"type":"string","description":"2-letter state code"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies":{"get":{"tags":["sec.companies"],"summary":"List companies (cursor-paginated by last_filing_date)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}":{"get":{"tags":["sec.companies"],"summary":"Company detail (accepts 10-digit CIK or stock ticker)","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"},"example":"AAPL"}],"responses":{"200":{"description":"Detail + recent filings + insider summary"}}}},"/api/v1/sec/companies/{cik_or_ticker}/insider-transactions":{"get":{"tags":["sec.insider"],"summary":"Form 4 transactions for this company","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":1000}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/insider-summary":{"get":{"tags":["sec.insider"],"summary":"Aggregated insider activity for this company across 7/30/90/365d windows","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/profile":{"get":{"tags":["sec.companies"],"summary":"Comprehensive dossier — basic info, recent filings, insider activity, financial facts","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/peers":{"get":{"tags":["sec.companies"],"summary":"Peer companies in the same SIC industry","description":"Ranked by most-recent filing date so the list surfaces actively-filing peers, not shell companies.","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":15,"maximum":100}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/insider-leaderboard":{"get":{"tags":["sec.insider"],"summary":"Top insiders by total $ activity across all companies","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"direction","in":"query","schema":{"type":"string","enum":["sells","buys","both"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/watchlist":{"get":{"tags":["sec.companies"],"summary":"Multi-ticker consolidated activity rollup","description":"Pass up to 25 tickers. One row per ticker with 30-day insider net flow, Form 144 sale pressure, recent material events, cluster-sell flag. Designed for portfolio-monitoring agents.","parameters":[{"name":"tickers","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated tickers (max 25)"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/ask":{"get":{"tags":["discovery"],"summary":"Natural-language → routed endpoint via Workers AI","description":"Ask in English. A small Llama model picks the right tool from the same set the /mcp server exposes and dispatches.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK with routed.{tool,arguments,reasoning} + result"}}}},"/api/v1/sec/most-active":{"get":{"tags":["sec.filings"],"summary":"Companies with the highest filing volume in a recent window","description":"High filing volume can indicate M&A activity, restructuring, IPO process, board changes, or distress.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"family","in":"query","schema":{"type":"string","description":"form_type_family filter (e.g. current_report, periodic, insider)"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/upcoming-earnings":{"get":{"tags":["sec.filings"],"summary":"Predict upcoming 10-Q/10-K filings from historical cadence","description":"Heuristic: gap between the most recent two filings of the same form ≈ gap to the next one. Companies do change cadence so this is approximate.","parameters":[{"name":"within_days","in":"query","schema":{"type":"integer","default":30,"maximum":120}},{"name":"form_type","in":"query","schema":{"type":"string","enum":["10-Q","10-K"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/8k/by-item":{"get":{"tags":["sec.filings"],"summary":"8-K filings filtered by item code (5.02 director departures, 1.01 M&A, 4.02 restatements, etc.)","description":"Returns 8-K filings whose parsed body has a section matching the requested item. Coverage limited by the 8-K body-extraction backlog. Item code can be 5.02, item-5-02, or 5-02 — normalized internally.","parameters":[{"name":"item","in":"query","required":true,"schema":{"type":"string","example":"5.02"}},{"name":"ticker","in":"query","schema":{"type":"string","description":"Filter to one company"}},{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/13d-positions/recent":{"get":{"tags":["sec.holdings"],"summary":"Structured Schedule 13D/G positions — parsed from primary_doc.xml","description":"Returns structured rows with target CUSIP, ticker, aggregate shares, percent of class. Newer 13D/G filings use a standardized XML schema; older HTML filings are best-effort regex-parsed.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":90,"maximum":365}},{"name":"min_percent","in":"query","schema":{"type":"number","description":"Filter to positions above N% of class"}},{"name":"filer_cik","in":"query","schema":{"type":"string"}},{"name":"filer","in":"query","schema":{"type":"string","description":"Filer ticker shorthand"}},{"name":"target_cusip","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/13dg/recent":{"get":{"tags":["sec.holdings"],"summary":"Recent Schedule 13D/G filings (activist + passive >5% holder positions)","description":"13D = activist intent, 13G = passive >5% holder, /A = amendment. Structured target/% extraction is TBD; this metadata view links to edgar_url.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"type","in":"query","schema":{"type":"string","enum":["13D","13G"]}},{"name":"filer_cik","in":"query","schema":{"type":"string"}},{"name":"issuer","in":"query","schema":{"type":"string","description":"Ticker or CIK best-effort match"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/upcoming-sales-pressure":{"get":{"tags":["sec.insider"],"summary":"Aggregate Form 144 sale pressure — companies with the most upcoming insider sales","description":"Forward-looking aggregation of Form 144 notices. Default groups by issuer; pass group_by=seller to find the most active sellers.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":180}},{"name":"group_by","in":"query","schema":{"type":"string","enum":["issuer","seller"],"default":"issuer"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/form144/brokers":{"get":{"tags":["sec.insider"],"summary":"Broker leaderboard from Form 144 — who's handling the most insider sale notices","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":180}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/form144/recent":{"get":{"tags":["sec.insider"],"summary":"Recent Form 144 notices — predictive insider-sale signal","description":"Filed before an affiliate sells restricted or control stock. Tracks seller, relationship, quantity, $, planned sale date. Complementary to Form 4 (post-trade).","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":7,"maximum":90}},{"name":"min_usd","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/risk-flags":{"get":{"tags":["sec.companies"],"summary":"Multi-source red-flag detector for one company","description":"Combines 8-K item parses (4.02 restatements, 4.01 auditor changes, 5.02 officer departures), insider cluster sells, Form 144 upcoming-sale pressure, Schedule 13D filings, FDA recalls against the firm, and FAERS adverse-event volume into one ranked flags array. Empty array = no red flags.","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/insider-network":{"get":{"tags":["sec.insider"],"summary":"Other companies sharing insiders with this one (interlocking directorates)","description":"Surfaces board interlock, multi-company executives, and activist-investor portfolio overlap by joining Form 4 reporting_owner_name across companies.","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/officers":{"get":{"tags":["sec.insider"],"summary":"Known officers/directors of one company, from Form 4 + Form 144","description":"Distinct named persons who've transacted or filed a sale notice. Not a complete roster — only people active in the data. Complete officer list requires DEF 14A parsing.","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/derivatives":{"get":{"tags":["sec.insider"],"summary":"Derivative-security transactions (RSU grants, option exercises, tax-withholding)","description":"Most insider endpoints filter these out. This view surfaces them so agents can answer 'what stock awards has this executive received?' price_per_share here is the option strike/cost basis, not the stock price.","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","default":180,"maximum":730}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/insider-pulse":{"get":{"tags":["sec.insider"],"summary":"Unified insider timeline — Form 4 trades + Form 144 proposed-sale notices","description":"Returns a single time-ordered feed for the company. Each event has kind=form4 (executed) or kind=form144 (notice of proposed sale). Tally section gives quick summary stats.","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","default":90,"maximum":365}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/form144":{"get":{"tags":["sec.insider"],"summary":"Form 144 notices for one company","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/insider-dashboard":{"get":{"tags":["sec.insider"],"summary":"One-call cross-company insider snapshot — cluster buys/sells + biggest trades + 144 pressure + weekly trend","description":"Saves agents from 4-5 separate calls when they just want 'what's happening with insiders today'.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":90}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/insider-trends":{"get":{"tags":["sec.insider"],"summary":"Insider buy/sell time-series — daily/weekly/monthly aggregates","description":"Open-market Form 4 transactions only (codes P, S), non-derivative, deduped per (txn × all reporters). Returns net_usd = bought_usd - sold_usd per bucket.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":90,"maximum":730}},{"name":"bucket","in":"query","schema":{"type":"string","enum":["day","week","month"],"default":"week"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/cluster-sells":{"get":{"tags":["sec.insider"],"summary":"Companies where multiple insiders sold stock in the same window (open-market sales only)","description":"Form 4 code S, non-derivative. Weaker signal than cluster-buys but spots mass insider exits.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"min_insiders","in":"query","schema":{"type":"integer","default":3,"minimum":2}},{"name":"min_usd","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/cluster-buys":{"get":{"tags":["sec.insider"],"summary":"Companies where multiple insiders bought stock in the same window (open-market purchases only)","description":"Form 4 code P, non-derivative. Classic conviction signal — insiders typically buy only when expecting upside.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":90,"maximum":365}},{"name":"min_insiders","in":"query","schema":{"type":"integer","default":3,"minimum":2}},{"name":"min_usd","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/insider-transactions/recent":{"get":{"tags":["sec.insider"],"summary":"Cross-company recent insider transactions","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":7,"maximum":90}},{"name":"min_usd","in":"query","schema":{"type":"number"}},{"name":"code","in":"query","schema":{"type":"string","description":"Transaction code (P, S, etc.)"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/holdings":{"get":{"tags":["sec.holdings"],"summary":"13F holdings of this filer (their portfolio)","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":5000}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/funds/largest-positions":{"get":{"tags":["sec.holdings"],"summary":"Largest single positions across the mutual-fund universe (NPORT-P)","description":"Surfaces concentrated positions and mega-stakes. Filter by min_pct for concentrated bets, min_value_usd for mega-stakes.","parameters":[{"name":"min_pct","in":"query","schema":{"type":"number","description":"Minimum % of fund net assets"}},{"name":"min_value_usd","in":"query","schema":{"type":"number"}},{"name":"period","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/fda/labels/recent":{"get":{"tags":["fda.recalls"],"summary":"Recent FDA drug labels (Structured Product Labeling)","parameters":[{"name":"product_type","in":"query","schema":{"type":"string","description":"e.g., 'HUMAN PRESCRIPTION DRUG'"}},{"name":"manufacturer","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/fda/labels/{name}":{"get":{"tags":["fda.recalls"],"summary":"FDA drug-label lookup by brand, generic, or substance name","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","description":"Substring match — e.g. 'aspirin' or 'COSENTYX'"}}],"responses":{"200":{"description":"OK with indications, dosage, warnings, adverse reactions, etc."}}}},"/api/v1/fda/firms/{name}":{"get":{"tags":["fda.recalls"],"summary":"All FDA activity for one firm — recalls + 510(k) clearances + adverse events","description":"Firm-level dossier. Recalls match on recalling_firm, clearances on applicant, adverse events on patient_drugs_json (best-effort).","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","description":"URL-encoded firm name substring (e.g., Pfizer)"}},{"name":"days","in":"query","schema":{"type":"integer","default":365,"maximum":1825}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/funds/{cik_or_series_id}/breakdown":{"get":{"tags":["sec.holdings"],"summary":"Mutual fund's asset/issuer/country breakdown","description":"Groups one NPORT-P fund's holdings into pct-of-portfolio buckets by asset_category (EC equity / DBT debt / STIV short-term), issuer_category (CORP / MUN / UST / RF fund-of-funds), and investment_country.","parameters":[{"name":"cik_or_series_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/funds/{cik_or_series_id}/holdings":{"get":{"tags":["sec.holdings"],"summary":"Holdings of one mutual fund (NPORT-P)","description":"Pass a 10-digit CIK (entire fund family) or a series_id like S000012345 (one fund). Latest report period by default.","parameters":[{"name":"cik_or_series_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":2000}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/securities/{cusip}/fund-holders":{"get":{"tags":["sec.holdings"],"summary":"Mutual funds (NPORT-P) holding a security by CUSIP","description":"Parallel to /top-holders (which uses 13F institutional data). NPORT-P covers mutual-fund holdings.","parameters":[{"name":"cusip","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/securities/{cusip}/top-holders":{"get":{"tags":["sec.holdings"],"summary":"Top 13F holders of a given security (by CUSIP)","parameters":[{"name":"cusip","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/13f/recent":{"get":{"tags":["sec.holdings"],"summary":"Recent 13F filings grouped by filer","parameters":[{"name":"period","in":"query","schema":{"type":"string","format":"date"}},{"name":"min_aum","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/timeline":{"get":{"tags":["sec.companies"],"summary":"Chronological event timeline (filings + insider transactions, mixed)","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/cross-vertical/active":{"get":{"tags":["entity"],"summary":"Entities with activity in 2+ regulatory verticals — discovery feed for the cross-vertical timeline","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":90,"maximum":365}},{"name":"min_verticals","in":"query","schema":{"type":"integer","default":2,"minimum":2,"maximum":4}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/entity/{key}/timeline":{"get":{"tags":["entity"],"summary":"Cross-vertical entity timeline — merges SEC filings, insider trades, Form 144, Schedule 13D, FDA recalls, FDA drug labels, federal contracts into one ordered feed","description":"Resolves `key` against entity_master (ticker, CIK, UEI, LEI, DUNS, or numeric entity_id) and joins against entity_alias to pull events across every vertical the entity appears in.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"},"example":"AAPL"},{"name":"days","in":"query","schema":{"type":"integer","default":180,"maximum":730}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}},{"name":"min_importance","in":"query","schema":{"type":"number","default":0,"description":"Filter to events scoring at or above this. Reference: Class I recall=100, 13D=75, large Form 144=75, insider buy=50, 8-K=35."}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/entity/{key}/material-events":{"get":{"tags":["entity"],"summary":"Material events only — entity timeline pre-filtered to min_importance=60","description":"Convenience shortcut: returns only events scoring 60 or above (Class I FDA recalls, Schedule 13D filings, large Form 144 notices, insider purchases). The 'alert me' feed.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"},"example":"BSX"},{"name":"days","in":"query","schema":{"type":"integer","default":180,"maximum":730}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/financial-facts/by-concept":{"get":{"tags":["sec.financials"],"summary":"Top N companies by a single XBRL metric","parameters":[{"name":"concept","in":"query","required":true,"schema":{"type":"string"},"example":"NetIncomeLoss"},{"name":"period","in":"query","schema":{"type":"string","default":"FY"}},{"name":"fiscal_year","in":"query","schema":{"type":"integer"}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/industries":{"get":{"tags":["sec.companies"],"summary":"SIC-grouped industries — counts + example tickers, or filter by SIC / keyword","parameters":[{"name":"sic","in":"query","schema":{"type":"string"},"description":"4-digit SIC code"},{"name":"keyword","in":"query","schema":{"type":"string"},"description":"Substring on industry description"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/securities/search":{"get":{"tags":["sec.companies"],"summary":"Unified security search: name, ticker, or CUSIP","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"example":"nvidia"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":200}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/news":{"get":{"tags":["discovery"],"summary":"Time-ordered cross-topic news (insider, recalls, weather, presidential docs, 8-Ks, cluster buys, 13D)","description":"Response includes 'available_kinds' listing every kind you can pass to ?kind=.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":3,"maximum":30}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"kind","in":"query","schema":{"type":"string","description":"Comma-separated allow-list (e.g. cluster_buy,form144,schedule_13d_new)"}},{"name":"topic","in":"query","schema":{"type":"string","description":"Filter to one topic (sec / fda / weather / register / climate)"}},{"name":"min_importance","in":"query","schema":{"type":"number","description":"Filter to high-signal events only. Reference: cluster_buy=85, presidential=80, 13D_new=75, alert_severe=60, 8k=30, Class I recall=100"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/help":{"get":{"tags":["discovery"],"summary":"Question → URL catalog for AI assistants","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Substring filter"}],"responses":{"200":{"description":"OK"}}}},"/api/v1/glossary":{"get":{"tags":["discovery"],"summary":"Lookup SEC/FDA/weather/register abbreviations","parameters":[{"name":"term","in":"query","schema":{"type":"string"},"example":"10-K"}],"responses":{"200":{"description":"OK"}}}},"/api/v1/agent-stats":{"get":{"tags":["discovery"],"summary":"Self-introspection — who's using this hub, by agent_source","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":7,"maximum":90}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/coverage":{"get":{"tags":["discovery"],"summary":"Operations snapshot — recent ingestion runs, queue depth, parse errors, freshness","responses":{"200":{"description":"OK"}}}},"/api/v1/dossier":{"get":{"tags":["discovery"],"summary":"Cross-topic entity lookup — name → matches across SEC + FDA + Register + Contracts + 13F","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string"},"example":"Pfizer"}],"responses":{"200":{"description":"OK"}}}},"/api/v1/climate/earthquakes/recent":{"get":{"tags":["climate"],"summary":"Recent USGS earthquakes (worldwide)","parameters":[{"name":"min_mag","in":"query","schema":{"type":"number","default":4}},{"name":"days","in":"query","schema":{"type":"integer","default":14,"maximum":90}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/sec/companies/{cik_or_ticker}/financial-facts":{"get":{"tags":["sec.financials"],"summary":"XBRL financial facts (revenue, EPS, net income, etc.)","parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"concept","in":"query","schema":{"type":"string"},"example":"NetIncomeLoss"},{"name":"period","in":"query","schema":{"type":"string","enum":["FY","Q1","Q2","Q3","Q4"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":40,"maximum":400}}],"responses":{"200":{"description":"Without concept: summary of latest values. With concept: full history."}}}},"/api/v1/sec/compare":{"get":{"tags":["sec.financials"],"summary":"Side-by-side financials for up to 10 companies","parameters":[{"name":"tickers","in":"query","required":true,"schema":{"type":"string"},"example":"AAPL,MSFT,GOOGL"},{"name":"concept","in":"query","schema":{"type":"string"},"description":"Single metric to compare; omit for default basket"},{"name":"period","in":"query","schema":{"type":"string","default":"FY"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/contracts/recent":{"get":{"tags":["contracts"],"summary":"Recent federal contract awards (USAspending — ingest pending)","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30}},{"name":"recipient","in":"query","schema":{"type":"string"}},{"name":"agency","in":"query","schema":{"type":"string"}},{"name":"min_obligation","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"OK (0 items today; schema-live, ingest pending)"}}}},"/api/v1/register/recent":{"get":{"tags":["register"],"summary":"Recent Federal Register documents (rules, proposed rules, notices, presidential docs)","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["Rule","Proposed Rule","Notice","Presidential Document"]}},{"name":"agency","in":"query","schema":{"type":"string"},"description":"Substring match on first agency name"},{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/register/executive-orders":{"get":{"tags":["register"],"summary":"Executive Orders (Presidential Documents with EO number)","responses":{"200":{"description":"OK"}}}},"/sec/{ticker_or_cik}/{form}/{period}/{section}":{"get":{"tags":["sec.sections"],"summary":"Filing section body (shadow-billed for AI crawlers)","description":"Returns the parsed body of a specific filing section. Currently free for all callers; AI-crawler hits are logged with price_micros=1000 (the shadow price) in agent_query_log. Real Pay Per Crawl will be enabled when DNS moves to a CF zone. Append .md, .html, or .json to control format (default: JSON envelope).","parameters":[{"name":"ticker_or_cik","in":"path","required":true,"schema":{"type":"string"},"example":"useg"},{"name":"form","in":"path","required":true,"schema":{"type":"string"},"example":"8-k"},{"name":"period","in":"path","required":true,"schema":{"type":"string"},"example":"2026-05-08"},{"name":"section","in":"path","required":true,"schema":{"type":"string"},"example":"item-5-02"}],"responses":{"200":{"description":"Section body (markdown/html/json)"},"404":{"description":"Section not found"}}}},"/fda/{product}/recalls/{recall_number}":{"get":{"tags":["fda.recalls"],"summary":"FDA recall detail (drug/device/food)","parameters":[{"name":"product","in":"path","required":true,"schema":{"type":"string","enum":["drug","device","food"]}},{"name":"recall_number","in":"path","required":true,"schema":{"type":"string"},"example":"D-0500-2026"}],"responses":{"200":{"description":"Recall summary (markdown or JSON envelope)"}}}},"/api/v1/fda/stats":{"get":{"tags":["fda.recalls"],"summary":"FDA aggregate counts","responses":{"200":{"description":"OK"}}}},"/api/v1/fda/recalls/recent":{"get":{"tags":["fda.recalls"],"summary":"Recent FDA enforcement actions (recalls)","parameters":[{"name":"product","in":"query","schema":{"type":"string","enum":["drug","device","food"]}},{"name":"class","in":"query","schema":{"type":"string","enum":["Class I","Class II","Class III"]}},{"name":"firm","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["Ongoing","Completed","Terminated"]}},{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/fda/adverse-events/recent":{"get":{"tags":["fda.adverse"],"summary":"Recent FAERS adverse event reports","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"drug","in":"query","schema":{"type":"string"},"example":"COSENTYX"},{"name":"reaction","in":"query","schema":{"type":"string"},"example":"Pneumonia"},{"name":"serious","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"outcome","in":"query","schema":{"type":"string","enum":["death","hospitalization","lifethreatening","disabling"]}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/fda/510k/recent":{"get":{"tags":["fda.510k"],"summary":"Recent FDA 510(k) medical device clearances","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"maximum":365}},{"name":"applicant","in":"query","schema":{"type":"string"},"example":"Medtronic"},{"name":"product_code","in":"query","schema":{"type":"string"}},{"name":"decision","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}