{"openapi":"3.0.3","info":{"title":"Marginal AI Enterprise REST API","version":"agent-2026-10","description":"Corporate and market events, figures as reported to the SEC, and macroeconomic series. Company API key required (Bearer mai_sk_...). Each successful data call uses 0.5 Compute Units from the company's shared allowance; taxonomy, industries, company resolution and macro series search are free. Impersonal factual research: no investment advice."},"servers":[{"url":"https://api.marginal-ai.com"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"security":[{"bearer":[]}],"paths":{"/api/v1/events":{"get":{"operationId":"search_events","summary":"Search corporate and market events","description":"Search Marginal AI's deduplicated, source-corroborated event record (SEC 8-K items, corroborated news) for a company, or across all companies for one category or event type within a window of at most 31 days. Each event carries its date, type, categories, the companies involved, a corroboration list with source links, and first_seen_ts (when Marginal AI first saw it: use known_as_of to reproduce what was knowable at a past moment, for backtests without lookahead). Paginate with next_cursor. Max 50 per call. Factual data only: it does not give investment advice and cannot place orders. Each call uses 0.5 of the user's Compute Units. Price: 0.5 Compute Units including up to 10 events, then 0.02 per further event. Plans below Enterprise have a monthly limit on distinct events; `monthly_events` in the response shows what is left.","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"type":"string"},"description":"Stock ticker, e.g. AAPL. Give ticker OR cik."},{"name":"cik","in":"query","required":false,"schema":{"type":"string"},"description":"SEC Central Index Key, digits only."},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"One of the 8 event categories: Regulatory & Legislative Actions; Mergers & Acquisitions (M&A) and Corporate Restructuring; Litigation & Legal Disputes; Operational & Technological Disruptions; Force Majeure & Environmental Events; Market & Economic Shocks; Accounting Adjustments and Other Non-Recurring Items; Earnings & Guidance. Call list_event_taxonomy for the exact strings."},{"name":"event_type","in":"query","required":false,"schema":{"type":"string"},"description":"Event type, e.g. 'Results of Operations'."},{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"Date, YYYY-MM-DD."},{"name":"until","in":"query","required":false,"schema":{"type":"string"},"description":"Date, YYYY-MM-DD."},{"name":"min_sources","in":"query","required":false,"schema":{"type":"number"},"description":"Minimum corroborating sources."},{"name":"known_as_of","in":"query","required":false,"schema":{"type":"string"},"description":"ISO timestamp: only events Marginal AI had seen by then (point-in-time)."},{"name":"limit","in":"query","required":false,"schema":{"type":"number"},"description":"Default 20."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"next_cursor from the previous page."}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/events/new":{"get":{"operationId":"get_new_events","summary":"Events first seen since a time (polling)","description":"Events Marginal AI first saw after `since` (at most 7 days back), oldest first, optionally for one company or category. Built for agents that poll: keep the returned high_watermark and pass it as `since` next time. Factual data only: it does not give investment advice and cannot place orders. Each call uses 0.5 of the user's Compute Units. Price: 0.5 Compute Units including up to 10 events, then 0.02 per further event. Plans below Enterprise have a monthly limit on distinct events; `monthly_events` in the response shows what is left.","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string"},"description":"ISO timestamp, at most 7 days ago."},{"name":"ticker","in":"query","required":false,"schema":{"type":"string"},"description":"Stock ticker, e.g. AAPL. Give ticker OR cik."},{"name":"cik","in":"query","required":false,"schema":{"type":"string"},"description":"SEC Central Index Key, digits only."},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"One of the 8 event categories: Regulatory & Legislative Actions; Mergers & Acquisitions (M&A) and Corporate Restructuring; Litigation & Legal Disputes; Operational & Technological Disruptions; Force Majeure & Environmental Events; Market & Economic Shocks; Accounting Adjustments and Other Non-Recurring Items; Earnings & Guidance. Call list_event_taxonomy for the exact strings."},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/events/{event_id}":{"get":{"operationId":"get_event","summary":"One event with its price reaction","description":"Full detail for one event_id, including every corroborating source and, by default, the stock's co-incident price reaction (abnormal return vs SPY and volume z-score over the trading-day window). The reaction is a measurement, not a claim that the event caused it. Factual data only: it does not give investment advice and cannot place orders. Each call uses 0.5 of the user's Compute Units.","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"include_price_reaction","in":"query","required":false,"schema":{"type":"boolean"},"description":"Default true."}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/companies/resolve":{"get":{"operationId":"resolve_company","summary":"Resolve a ticker or CIK","description":"Map a ticker to its SEC CIK and name (or the reverse), with industry and whether it files XBRL financial statements. Free: uses no Compute Units.","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"type":"string"},"description":"Stock ticker, e.g. AAPL. Give ticker OR cik."},{"name":"cik","in":"query","required":false,"schema":{"type":"string"},"description":"SEC Central Index Key, digits only."}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/companies/{company}/events":{"get":{"operationId":"get_company_events","summary":"A company's event timeline (company = ticker or CIK)","description":"A company's events between two dates (default: the last year), newest first or ranked by materiality (size of the co-incident price and volume reaction). Up to 100 events, 50 when ranked by materiality. Factual data only: it does not give investment advice and cannot place orders. Each call uses 0.5 of the user's Compute Units. Price: 0.5 Compute Units including up to 10 events, then 0.02 per further event. Plans below Enterprise have a monthly limit on distinct events; `monthly_events` in the response shows what is left.","parameters":[{"name":"company","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker (e.g. AAPL) or SEC CIK (digits)."},{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"Date, YYYY-MM-DD."},{"name":"until","in":"query","required":false,"schema":{"type":"string"},"description":"Date, YYYY-MM-DD."},{"name":"rank_by","in":"query","required":false,"schema":{"type":"string","enum":["date","materiality"]}},{"name":"include_price_reaction","in":"query","required":false,"schema":{"type":"boolean"},"description":"Default false."},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/taxonomy":{"get":{"operationId":"list_event_taxonomy","summary":"Event categories and types","description":"The exact category and event-type strings the event tools accept. Free: uses no Compute Units.","parameters":[],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/industries":{"get":{"operationId":"list_industries","summary":"Industry groups and their companies","description":"The industry groups Marginal AI covers (the same groups as its Industries filter), each with its company count. Pass industry to list the companies in one group (tickers and CIKs to use with the other tools). Free: uses no Compute Units.","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string"},"description":"Filter group names, e.g. 'bank' or 'semiconductor'."},{"name":"industry","in":"query","required":false,"schema":{"type":"string"},"description":"An exact group name from this tool: returns its companies."},{"name":"limit","in":"query","required":false,"schema":{"type":"number"},"description":"Max companies returned with industry. Default 200."}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/financials/fact":{"get":{"operationId":"get_sec_fact","summary":"One reported financial figure","description":"One figure exactly as the company reported it to the SEC in XBRL (e.g. revenue, net income, operating cash flow) for a fiscal year or quarter, with the concept tag, period, form, filing date, accession number and a link to the filing. Factual data only: it does not give investment advice and cannot place orders. Each call uses 0.5 of the user's Compute Units.","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"type":"string"},"description":"Stock ticker, e.g. AAPL. Give ticker OR cik."},{"name":"cik","in":"query","required":false,"schema":{"type":"string"},"description":"SEC Central Index Key, digits only."},{"name":"metric","in":"query","required":true,"schema":{"type":"string"},"description":"Metric key, e.g. revenue, net_income, eps_diluted."},{"name":"fiscal_year","in":"query","required":true,"schema":{"type":"number"}},{"name":"fiscal_quarter","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/financials/series":{"get":{"operationId":"get_sec_fact_series","summary":"A reported financial figure over time","description":"A series of one reported XBRL figure, annual (up to 12 years) or quarterly (up to 16 quarters), oldest first, each point sourced to its filing. Factual data only: it does not give investment advice and cannot place orders. Each call uses 0.5 of the user's Compute Units.","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"type":"string"},"description":"Stock ticker, e.g. AAPL. Give ticker OR cik."},{"name":"cik","in":"query","required":false,"schema":{"type":"string"},"description":"SEC Central Index Key, digits only."},{"name":"metric","in":"query","required":true,"schema":{"type":"string"}},{"name":"granularity","in":"query","required":false,"schema":{"type":"string","enum":["annual","quarterly"]}},{"name":"start_year","in":"query","required":false,"schema":{"type":"number"}},{"name":"end_year","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/macro/series":{"get":{"operationId":"list_macro_series","summary":"Find macroeconomic series","description":"Search the macroeconomic series Marginal AI tracks (rates, inflation, employment, growth, commodities and more) by keyword or provider; returns series_key values for get_macro_series. Free: uses no Compute Units.","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}},"/api/v1/macro/series/{series_key}":{"get":{"operationId":"get_macro_series","summary":"One macroeconomic series","description":"Observations of one macro series (up to 500 points, most recent by default), with units, frequency and how stale the latest point is. Factual data only: it does not give investment advice and cannot place orders. Each call uses 0.5 of the user's Compute Units.","parameters":[{"name":"series_key","in":"path","required":true,"schema":{"type":"string"}},{"name":"start","in":"query","required":false,"schema":{"type":"string"},"description":"Date, YYYY-MM-DD."},{"name":"end","in":"query","required":false,"schema":{"type":"string"},"description":"Date, YYYY-MM-DD."},{"name":"max_points","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Envelope: api_version, tool, as_of, cu_charged, attribution, notice, data."},"400":{"description":"invalid_arguments"},"401":{"description":"Missing, invalid, expired or revoked key"},"402":{"description":"insufficient_balance: the company's Compute Units or overage limit"},"403":{"description":"enterprise_required, terms_required or account_unavailable"},"404":{"description":"not_found"},"429":{"description":"rate_limited / busy / daily_call_limit / monthly_event_limit (see Retry-After)"}}}}}}