{ "schema_version": "1.0", "name": "Astreus data tools", "api_version": "2026-11-12", "spec_sha256": "aa6f83fcc3bf76c346e4fbb1a634b8a0aa04728fdd79967116eb0828067ac494", "base_url": "https://astreus.ai", "openapi_url": "https://astreus.ai/openapi.json", "mcp_url": "https://astreus.ai/api/mcp", "tool_discovery": "MCP clients must use tools/list on their connected server. This catalog describes the matching source release; deployed capabilities may lag until that release is installed.", "operations": [ { "id": "get-private-company-profile", "method": "GET", "path": "/api/v1/supercycle/private/{slug}", "title": "Private company profile", "description": "Published private-company profile, funding, KPIs, fund valuation marks and source-linked counterparty claims. Use the registry slug or canonical XPRV platform key. Fund marks and reported valuations are not exchange quotes; preserve each observation's provenance and date. Internal review data is excluded on the deployed site.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Registry slug or canonical private-company platform key.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company" ], "callable": true }, { "id": "get-private-company-filed-record", "method": "GET", "path": "/api/v1/supercycle/private/{slug}/filed", "title": "Private company filed record", "description": "Private-company filed record: Form D offerings, third-party SPV filings and fund-reported credit marks. Accession-numbered evidence only; an SPV's offering is not the operating company's own fundraising.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Registry slug or canonical private-company platform key.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company" ], "callable": true }, { "id": "get-crypto-asset-screener", "method": "GET", "path": "/api/v1/crypto", "title": "Crypto asset screener", "description": "Tracked crypto assets ranked by market cap, daily closes and returns, priced in the requested fiat currency. Preserve the returned CoinGecko attribution; these are daily reference observations, not executable quotes.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "vs", "in": "query", "description": "Fiat ISO currency on the FX board.", "schema": { "type": "string", "default": "USD" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-crypto-asset-profile", "method": "GET", "path": "/api/v1/crypto/{id}", "title": "Crypto asset profile", "description": "One crypto asset's profile, supply and USD reference prices. The identifier is the CoinGecko coin ID, such as bitcoin. Preserve the returned CoinGecko attribution.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "CoinGecko coin ID.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-crypto-price-history", "method": "GET", "path": "/api/v1/crypto/{id}/prices", "title": "Crypto price history", "description": "Daily USD closes from CoinGecko snapshots, from the first day of `range` to the latest. Open, high and low repeat the close; these are close-only bars. History starts where the CoinGecko backfill did (about 365 days before the section launched on 2026-10-28), so 2Y, 5Y and ALL start there: `coverageFrom` is the first day held and `note` says so. `lookback` adds earlier bars for moving averages; `displayFrom` is the epoch ms of the first bar inside the range. An unknown coin is a 404. Preserve source attribution.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "CoinGecko coin ID.", "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "Window of bars served: from the range's first day to the latest bar.", "schema": { "type": "string", "enum": [ "1M", "3M", "6M", "YTD", "1Y", "2Y", "5Y", "ALL" ], "default": "1Y", "x-case-insensitive": true } }, { "name": "lookback", "in": "query", "description": "Bars to add before the range's first day (e.g. 200 for a 200-day moving average). Default 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-printed-statement-by-period", "method": "GET", "path": "/api/v1/companies/{id}/financials/as-reported", "title": "Printed statement by period", "description": "Printed statement tables by reporting period, from the legacy lane: statements read from the filed documents before XBRL (for SEC registrants, periods before about 2010; for NVDA the newest is 2009-10-25). For later periods use /financials (standardized) or /financials/as-filed (the filer's own XBRL tree). With statement only, lists the winning documents; with period and periodicity, returns the printed captions and cells. Retain source evidence and period basis.", "groups": [ "Financial Statements" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker, SEC CIK or canonical platform key returned by company resolution.", "schema": { "type": "string" } }, { "name": "statement", "in": "query", "description": "Statement to retrieve.", "schema": { "type": "string", "enum": [ "income_statement", "balance_sheet", "cash_flow_statement" ] }, "required": true }, { "name": "period", "in": "query", "description": "Period end YYYY-MM-DD; omit to list periods.", "schema": { "type": "string" } }, { "name": "periodicity", "in": "query", "description": "Required when period is supplied.", "schema": { "type": "string", "enum": [ "annual", "quarterly" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_financials_as_filed" ], "callable": true }, { "id": "get-earnings-source-statements", "method": "GET", "path": "/api/v1/companies/{id}/earnings/statements", "title": "Earnings source statements", "description": "Verified statements from the issuer's speakers, by extraction type, newest call first. Retains source call and quote anchors; a speaker's causal claim is not independently proven causation. Retains source call and quote anchors; a speaker's causal claim is not independently proven causation.", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker, SEC CIK or canonical platform key returned by company resolution.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Extraction type.", "schema": { "type": "string", "enum": [ "causal_claim", "guidance", "metric", "event", "state" ], "default": "causal_claim" } }, { "name": "document", "in": "query", "description": "Limit to one source document ID (an integer).", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Text contained in the statement, its quote, concept, cause, effect or speaker name; max 200 characters.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–100; default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_earnings" ], "callable": true }, { "id": "get-company-regulators", "method": "GET", "path": "/api/v1/companies/{id}/regulators", "title": "Company regulators", "description": "Government bodies that regulate the issuer, with role and the sentence supporting the relationship.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker, SEC CIK or canonical platform key returned by company resolution.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government_exposure" ], "callable": true }, { "id": "get-fx-pair-profile", "method": "GET", "path": "/api/v1/fx/pairs/{pair}", "title": "FX pair profile", "description": "Reference-rate currency pair profile: latest cross, historical returns and derived range/volatility statistics, with canonical orientation and redenomination metadata. These are reference rates, not executable quotes.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "pair", "in": "path", "required": true, "description": "Six-letter currency pair, for example USDCAD.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_market_series" ], "callable": true }, { "id": "get-companies-with-physical-assets", "method": "GET", "path": "/api/v1/geo/companies", "title": "Companies with physical assets", "description": "Published companies with physical assets in the map registry and counts visible to the caller. Draft preview is a local-only development feature.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_asset_companies" ], "callable": true }, { "id": "get-company-digital-assets", "method": "GET", "path": "/api/v1/companies/{id}/digital-assets", "title": "Company digital assets", "description": "The issuer's held digital assets and their source-linked attributes. REST may include fields whose redistribution is filtered by the corresponding MCP tool.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker, SEC CIK or canonical platform key returned by company resolution.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_digital_assets" ], "callable": true }, { "id": "get-digital-asset-detail", "method": "GET", "path": "/api/v1/digital-assets/{key}", "title": "Digital asset detail", "description": "One digital asset by stable key, with current and historical holders, lifecycle, specification and available alternative data. The holder must be a published company.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Digital asset key returned by the company's asset register.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_digital_assets" ], "callable": true }, { "id": "get-person-roll-call-votes", "method": "GET", "path": "/api/v1/people/{cik}/votes", "title": "Person roll call votes", "description": "A member of Congress's recorded roll-call votes, with bill and party context. Returns available=false for a person without this coverage.", "groups": [ "Ownership & Insiders" ], "tier": "free", "parameters": [ { "name": "cik", "in": "path", "required": true, "description": "Canonical person key.", "schema": { "type": "string" } }, { "name": "congress", "in": "query", "description": "Congress number (1–200) or all; default the newest held. A congress not held falls back to the newest.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–200; default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_person" ], "callable": true }, { "id": "get-conflict-detail", "method": "GET", "path": "/api/v1/military/conflicts/{key}", "title": "Conflict detail", "description": "One published conflict with parties, their periods, reported outcomes and source evidence. Draft review actions are not exposed by this operation.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Conflict key returned by search or the conflict index, e.g. ucdp:14609.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_conflict" ], "callable": true }, { "id": "get-organisation-detail", "method": "GET", "path": "/api/v1/foreign-relations/organisations/{code}", "title": "Organisation detail", "description": "One published international organisation, its bodies, country seats over time and linked agreements. An empty production registry does not include drafts.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Organisation code returned by the index.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_organisation" ], "callable": true }, { "id": "get-legislative-bills", "method": "GET", "path": "/api/v1/countries/{iso}/government/bills", "title": "Legislative bills", "description": "Legislative measures and their derived action stages, with whole-population stage counts and bounded result pages.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO alpha-2 country code.", "schema": { "type": "string" } }, { "name": "congress", "in": "query", "description": "Congress number (1–200) or all; default the newest held. A congress not held falls back to the newest.", "schema": { "type": "string" } }, { "name": "stage", "in": "query", "description": "Action stage.", "schema": { "type": "string", "enum": [ "introduced", "passed_one", "cleared", "law", "vetoed" ] } }, { "name": "voted", "in": "query", "description": "1 to require a recorded vote.", "schema": { "type": "string", "enum": [ "1", "0" ] } }, { "name": "q", "in": "query", "description": "Title contains; max 120 characters.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–200; default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-next-chamber-sittings", "method": "GET", "path": "/api/v1/countries/{iso}/government/next-sitting", "title": "Next chamber sittings", "description": "The next published chamber sitting and programme, plus the surrounding calendar. A null next sitting means nothing published within the returned horizon, not a declaration of recess.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO alpha-2 country code.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-government-committee", "method": "GET", "path": "/api/v1/countries/{iso}/government/committees/{systemCode}", "title": "Government committee", "description": "Committee roster, subcommittees and meeting/hearing log for the selected Congress.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO alpha-2 country code.", "schema": { "type": "string" } }, { "name": "systemCode", "in": "path", "required": true, "description": "Committee system code from government data.", "schema": { "type": "string" } }, { "name": "congress", "in": "query", "description": "Congress number (1–200) or all; default the newest held. A congress not held falls back to the newest.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-government-roll-call-vote", "method": "GET", "path": "/api/v1/countries/{iso}/government/votes/{congress}/{chamber}/{session}/{roll}", "title": "Government roll call vote", "description": "One roll call by its natural key, including how each member voted. Separate from the bills page to keep large rosters bounded to one selected vote.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO alpha-2 country code.", "schema": { "type": "string" } }, { "name": "congress", "in": "path", "required": true, "description": "congress", "schema": { "type": "string" } }, { "name": "chamber", "in": "path", "required": true, "description": "Chamber code from the source vote reference.", "schema": { "type": "string" } }, { "name": "session", "in": "path", "required": true, "description": "session", "schema": { "type": "string" } }, { "name": "roll", "in": "path", "required": true, "description": "roll", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-government-budget-flow", "method": "GET", "path": "/api/v1/countries/{iso}/budget-flow", "title": "Government budget flow", "description": "United States only: fiscal-year receipts by source and net outlays by function from Monthly Treasury Statement Table 9 (September, fiscal year to date), in billions of dollars, oldest year first. Any other country is a 404 (`not_found`): the statement covers the United States only.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO alpha-2 country code.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-central-bank-financial-source", "method": "GET", "path": "/api/v1/countries/{iso}/fed-financials/source", "title": "Central bank financial source", "description": "Primary-source evidence for one served Federal Reserve statement figure, including document vintages, page/box/text anchors, and arithmetic for a derived Q4 where applicable.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO alpha-2 country code.", "schema": { "type": "string" } }, { "name": "entity", "in": "query", "description": "Reporting entity.", "schema": { "type": "string", "default": "combined" } }, { "name": "statement", "in": "query", "description": "Statement identifier from the served grid.", "schema": { "type": "string" }, "required": true }, { "name": "line", "in": "query", "description": "Line identifier from the served grid.", "schema": { "type": "string" }, "required": true }, { "name": "period_end", "in": "query", "description": "Reporting period end YYYY-MM-DD.", "schema": { "type": "string" }, "required": true }, { "name": "duration", "in": "query", "description": "Period duration from the served cell; zero for a balance sheet.", "schema": { "type": "integer", "minimum": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_central_bank_financials" ], "callable": true }, { "id": "get-company-research-widget", "method": "GET", "path": "/api/v1/research/widgets/{kind}", "title": "Company research widget", "description": "Normalized source-bearing research widget for a ticker. The MCP tool restricts kinds and licensed fields; REST availability does not imply unrestricted redistribution.", "groups": [ "Analytics" ], "tier": "free", "parameters": [ { "name": "kind", "in": "path", "required": true, "description": "One of historical_valuation, guidance_tracker, narrative_radar, ownership_crowding, earnings_quality, segment_momentum, event_study, filing_diff, statement_xray, macro_release_monitor, causal_exposure, compute_economics, corporate_actions_timeline, capital_allocation, manager_portfolio, release_filing_reconciliation, insider_activity_tape, data_confidence. Unknown kind: 404.", "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "description": "Ticker; default NVDA.", "schema": { "type": "string", "default": "NVDA" } }, { "name": "offset", "in": "query", "description": "statement_xray: nodes to skip; the readout lists 160 a page. Other kinds ignore it.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_research_widget" ], "callable": true }, { "id": "get-federal-awards", "method": "GET", "path": "/api/v1/companies/{id}/government-awards", "title": "Federal awards", "description": "Federal awards (USAspending) to the company's mapped recipient UEIs. A company reaches federal money only through an evidence-backed UEI mapping, never a name match; awards is null when none is mapped.", "groups": [ "Companies" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government_exposure" ], "callable": true }, { "id": "get-regulation", "method": "GET", "path": "/api/v1/companies/{id}/regulation", "title": "Regulation", "description": "Government documents that bear on the company, each with the evidence that ties it there. executiveActions[] carries every link basis per document, strongest first: named (the document's text names the company), company_cited (the company's own periodic report cites or describes the order; evidence is the company's sentence and its accession), sector (the order acts directly on the company's industry; evidence is the order's own text). A link is never a look-alike name. coverage reports how much of the record has been read — a short list is not 'no exposure' until it is whole. Pilot coverage.", "groups": [ "Companies" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government_exposure" ], "callable": true }, { "id": "get-laws-regulations", "method": "GET", "path": "/api/v1/companies/{id}/laws", "title": "Laws & regulations", "description": "The laws and regulations that affect the company outside the US (e.g. Dubai for Salik), read at article level (gov_legal_company_link_served) and grouped per instrument: { cik, articleCount, instruments: [{ docId, jurisdiction, docType, docTypeLabel, number, year, titleEn, titleAr, titleEnDisplay (official English title, else a machine translation), titleEnIsMachine, titleEnMachine, issueDate, effectiveDate, status, isHistorical, basis (named | activity | amends_tagged | sector), basisRank (1–4), effects[] (establishes, concession, sets_tariff, sets_fines, exemptions, enforcement_powers, operations, licensing, governance, other — most important first), governanceOnly, via ({ docId, relation, docType, number, year, titleEn, titleAr, titleEnMachine } — the law an amending instrument is tied through), sourcePageUrl, pdfUrlEn, pdfUrlAr, articles: [{ linkId, articleRef, articleLabel, effect, quoteLang, quote, quoteTranslationEn, translationIsMachine, explanation, judgeVerdict, basis }] }] }. Ordered in force first, newest issue date first (an undated instrument by its year), then by basis; repealed instruments last in the same order. The US counterpart is GET /companies/{id}/regulation.", "groups": [ "Companies" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Instruments per page, 1–50, default 20; adds total, offset, limit, hasMore and nextOffset. Without limit, offset or q every instrument is served (about 180 KB for Salik).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "description": "Instruments to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "description": "Words that must all appear in an instrument's own fields (title, number, issuer, …); pages the matches.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government_exposure" ], "callable": true }, { "id": "get-company-debt-disclosures", "method": "GET", "path": "/api/v1/companies/{id}/debt", "title": "Company debt disclosures", "description": "Source-backed debt disclosures: instruments, borrowing groups, financing programmes and filed ladders. Partial pilot coverage. Preserve amount basis, currency, reporting date and source_id; null is not zero. Equity-classified capital instruments are labelled separately and excluded from debt totals.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "as_of", "in": "query", "description": "Public information through this UTC date, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Instrument or issuer contains; max 100 characters.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "description": "Native ISO currency in upper case, e.g. USD.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Instrument kind: note includes subordinated, Tier 2 and AT1 notes; sukuk includes AT1 sukuk; loan is term loans and loans; capital is equity-classified capital instruments.", "schema": { "type": "string", "enum": [ "bond", "note", "sukuk", "loan", "capital", "group" ] } }, { "name": "include_prior", "in": "query", "description": "Include prior-only disclosures; these do not establish current outstanding status.", "schema": { "type": "boolean", "default": true } }, { "name": "include_matured", "in": "query", "description": "Include matured instruments and those the issuer shows as repaid or redeemed or the exchange delisted; default excludes them without deleting their evidence.", "schema": { "type": "boolean", "default": false } }, { "name": "sort", "in": "query", "description": "Amounts sort by their USD value at the cutoff (daily reference rates); an amount whose currency has no rate sorts last.", "schema": { "type": "string", "enum": [ "maturity", "coupon", "amount", "issuer" ], "default": "maturity" } }, { "name": "direction", "in": "query", "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "limit", "in": "query", "description": "Instruments per page, 1–100 (above 100 is a 400). Each instrument brings its cited sources, ~6 KB.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "`page_info.nextCursor` from the previous page (`next_cursor` is its deprecated alias); `page_info.hasMore` is false on the last page. Revision-bound: restart from the first page if the data or filters change.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company_debt" ], "callable": true }, { "id": "get-instrument-disclosure-history-and-evidence-scoped-to-its-reporting-company", "method": "GET", "path": "/api/v1/companies/{id}/debt/{instrumentId}", "title": "Instrument disclosure history and evidence, scoped to its reporting company.", "description": "Instrument disclosure history and evidence, scoped to its reporting company.", "groups": [ "companies" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "instrumentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "as_of", "in": "query", "description": "Public information through this UTC date, YYYY-MM-DD.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company_debt" ], "callable": true }, { "id": "get-debt-source-evidence", "method": "GET", "path": "/api/v1/companies/{id}/debt/sources/{sourceId}", "title": "Debt source evidence", "description": "Original debt evidence with immutable document hash, locator and excerpt; scoped to the reporting company.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company_debt" ], "callable": true }, { "id": "get-bond-issuer-screener", "method": "GET", "path": "/api/v1/debt/issuers", "title": "Bond issuer screener", "description": "Corporate bond screener grouped by reporting company, with bond counts, maturity span, coupon range and denominations. Largest market cap first by default; issuer disclosures, not market prices or yields.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "as_of", "in": "query", "description": "Public information through this UTC date, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Instrument or issuer contains; max 100 characters.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "description": "Native ISO currency in upper case, e.g. USD.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Instrument kind: note includes subordinated, Tier 2 and AT1 notes; sukuk includes AT1 sukuk; loan is term loans and loans; capital is equity-classified capital instruments.", "schema": { "type": "string", "enum": [ "bond", "note", "sukuk", "loan", "capital", "group" ] } }, { "name": "include_prior", "in": "query", "description": "Include prior-only disclosures; these do not establish current outstanding status.", "schema": { "type": "boolean", "default": true } }, { "name": "include_matured", "in": "query", "description": "Include matured instruments and those the issuer shows as repaid or redeemed or the exchange delisted; default excludes them without deleting their evidence.", "schema": { "type": "boolean", "default": false } }, { "name": "sort", "in": "query", "description": "Company sort order.", "schema": { "type": "string", "enum": [ "market_cap", "bonds", "issuer", "maturity", "coupon" ], "default": "market_cap" } }, { "name": "direction", "in": "query", "description": "Sort direction; default desc for market_cap and bonds, asc otherwise.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "company", "in": "query", "description": "Repeat for up to 50 exact CIKs or platform keys.", "schema": { "type": "array", "items": { "type": "string" } } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "screen_corporate_bonds" ], "callable": true }, { "id": "get-corporate-bond-screener", "method": "GET", "path": "/api/v1/debt/instruments", "title": "Corporate bond screener", "description": "Corporate bond disclosure screener: individually disclosed bonds, notes, sukuk and labelled capital instruments. No borrowing groups, market prices, yields or ratings; partial pilot coverage.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "as_of", "in": "query", "description": "Public information through this UTC date, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Instrument or issuer contains; max 100 characters.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "description": "Native ISO currency in upper case, e.g. USD.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Instrument kind: note includes subordinated, Tier 2 and AT1 notes; sukuk includes AT1 sukuk; loan is term loans and loans; capital is equity-classified capital instruments.", "schema": { "type": "string", "enum": [ "bond", "note", "sukuk", "loan", "capital", "group" ] } }, { "name": "include_prior", "in": "query", "description": "Include prior-only disclosures; these do not establish current outstanding status.", "schema": { "type": "boolean", "default": true } }, { "name": "include_matured", "in": "query", "description": "Include matured instruments and those the issuer shows as repaid or redeemed or the exchange delisted; default excludes them without deleting their evidence.", "schema": { "type": "boolean", "default": false } }, { "name": "sort", "in": "query", "description": "Amounts sort by their USD value at the cutoff (daily reference rates); an amount whose currency has no rate sorts last.", "schema": { "type": "string", "enum": [ "maturity", "coupon", "amount", "issuer" ], "default": "maturity" } }, { "name": "direction", "in": "query", "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "limit", "in": "query", "description": "Instruments per page, 1–100 (above 100 is a 400). Each instrument brings its cited sources, ~6 KB.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "`page_info.nextCursor` from the previous page (`next_cursor` is its deprecated alias); `page_info.hasMore` is false on the last page. Revision-bound: restart from the first page if the data or filters change.", "schema": { "type": "string" } }, { "name": "company", "in": "query", "description": "Repeat for up to 50 exact CIKs or platform keys.", "schema": { "type": "array", "items": { "type": "string" } } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company_debt", "screen_corporate_bonds" ], "callable": true }, { "id": "get-debt-instrument-detail", "method": "GET", "path": "/api/v1/debt/instruments/{instrumentId}", "title": "Debt instrument detail", "description": "One bond, note or sukuk as its own instrument: current record (issuer, disclosed terms, latest disclosure, prior flag) and every filing that disclosed it with evidence. Issuer disclosures only; no market prices, yields or ratings.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "instrumentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "as_of", "in": "query", "description": "Public information through this UTC date, YYYY-MM-DD.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "screen_corporate_bonds" ], "callable": true }, { "id": "get-health-check", "method": "GET", "path": "/api/health", "title": "Health check", "description": "Liveness probe.", "groups": [ "Search & Meta" ], "tier": "public", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-coverage-stats", "method": "GET", "path": "/api/v1/landing/stats", "title": "Coverage stats", "description": "Headline counts shown on the landing page: economies, companies, their combined USD market value, people, commodities, indices, observations and narratives.", "groups": [ "Search & Meta" ], "tier": "public", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-coverage-inventory", "method": "GET", "path": "/api/v1/landing/coverage", "title": "Coverage inventory", "description": "The live coverage inventory — what Astreus holds right now, straight from the serving tables, refreshed hourly. Universe totals (companies by sector and exchange, filings by year and type, facts, prices, macro series, transcripts, observations, narratives, guidance commitments, central-bank documents) plus `markets[]`: for every country served, its exchanges, published companies, the earliest reporting period held, the median completeness score, served note tables, and for each data type (financial statements, segments & KPIs, report documents, filing notes, earnings releases, transcripts, audio, investor presentations, 13F holdings) the reporting periods held versus the periods that exist. Ask this before answering \"what is your coverage of market X?\".", "groups": [ "Search & Meta" ], "tier": "public", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_coverage" ], "callable": true }, { "id": "get-search", "method": "GET", "path": "/api/v1/search", "title": "Search", "description": "Global search across companies (public and private), macro series and countries. Companies are matched on any listed symbol, name, legal/former names and curated aliases (\"chatgpt\" finds OpenAI), with typo tolerance. `scope` adds the other entities. Alternatively pass `domains` (no `q`) to resolve brand web domains to covered companies.", "groups": [ "Search & Meta" ], "tier": "free", "parameters": [ { "name": "q", "in": "query", "description": "Search text.", "schema": { "type": "string" } }, { "name": "domains", "in": "query", "description": "Comma-separated brand domains to resolve when `q` is empty; domains beyond the 8th are ignored; at most 6 companies return.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1–20, default 8.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } }, { "name": "scope", "in": "query", "description": "`curated` (default): companies, the series a country page opens, countries. `all`: every national and first-level-regional series that holds data, each with `geo` and `id` (GEO:KEY, read with /countries/{geo}/series?key=), plus `commodities`, `fx_pairs`, `people`, `conflicts`, `organisations` and `bonds`, each row with the `id` its route takes and a `score`. `terminal`: the curated series, those six and `crypto` and `indices` (names and ids only, the rows of the terminal's search box). `all` and `terminal` add `interpretations`: what the whole query reads as, by plain rules (\"nvda earnings\" → NVIDIA's Earnings tab, \"uae inflation\" → that country's series, \"war in the middle east\" → conflicts there), each with a `target` naming the page it opens.", "schema": { "type": "string", "enum": [ "curated", "all", "terminal" ], "default": "curated" } }, { "name": "country", "in": "query", "description": "Series: only this ISO alpha-2 country and its regions.", "schema": { "type": "string" } }, { "name": "natural", "in": "query", "description": "1 = a submitted query, perhaps a typed question: when the literal query finds little, rows from the words that carry it join in, and rows scoring under 50 are dropped.", "schema": { "type": "string", "enum": [ "1" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "search" ], "callable": true }, { "id": "get-search-news-themes-and-transcripts", "method": "GET", "path": "/api/v1/search/content", "title": "Search news, themes and transcripts", "description": "What a query finds in news, market themes and call transcripts, by its words and by its meaning: each section merges a keyword search with a search of the stored document vectors (Cohere Embed v4), ranked together; `meaning` false says that section is words only (search syntax, a company + topic query, or the meaning search was unavailable). Call rows found by meaning are verified quotes with `matchedBy` \"meaning\". A typed question is reduced to the words that carry it (`terms`), and quoted phrases, OR and -exclusion are honoured as typed. A company and a topic (\"nvda earnings\") are searched within that company. A section with `relaxed` true holds looser rows, because no row had every word and meaning found nothing: all but one of the words, or the company's rows without the topic word. `failed` true means that section's search failed. News rows with the words in the headline lead. Transcripts look back 12 months.", "groups": [ "Search & Meta" ], "tier": "free", "parameters": [ { "name": "q", "in": "query", "description": "Search text.", "schema": { "type": "string", "required": true } }, { "name": "section", "in": "query", "description": "Only this section; all three when omitted.", "schema": { "type": "string", "enum": [ "news", "themes", "transcripts" ] } }, { "name": "limit", "in": "query", "description": "1–20 per section, default 8.", "schema": { "type": "integer" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "search" ], "callable": true }, { "id": "get-who-am-i", "method": "GET", "path": "/api/v1/me", "title": "Who am I", "description": "The calling key's account, plan, limits and live usage — the only account surface an API key can read. Returns the key's display prefix (never the secret), effective plan, per-minute/day/month limits and how much of each remains.", "groups": [ "Search & Meta" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-list-companies", "method": "GET", "path": "/api/v1/companies", "title": "List companies", "description": "List published companies. The response carries `total` and a per-country `countries[]` facet. Each row's `routeKey` (ticker for an SEC registrant, else the platform key = `cik`) is the identifier to pass to /companies/{id}; `id` is an internal record id (the primary security's, or the company's when it has no quote) that no route accepts.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "country", "in": "query", "description": "ISO-2 country code (US, SA, AE, JP, …); an invalid code is ignored.", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "description": "Filter by sector name.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Name, legal name or ticker contains, plus the global search's top 25 matches (aliases, typos).", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "public (default) = listed companies; private = the private-company lane (XPRV keys); all = both; delisted = listed issuers with a recorded delisting date. Another value is a 400.", "schema": { "type": "string", "enum": [ "public", "private", "all", "delisted" ], "default": "public" } }, { "name": "sort", "in": "query", "description": "Sort column; default market-cap ranking.", "schema": { "type": "string", "enum": [ "name", "price", "net_change", "change", "volume", "market_cap", "pe" ] } }, { "name": "direction", "in": "query", "description": "asc or desc (default).", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "description": "1–1000, default 100; above 1000 is a 400 (page with offset).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "offset", "in": "query", "description": "Default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_companies" ], "callable": true }, { "id": "get-price-sparklines", "method": "GET", "path": "/api/v1/companies/sparklines", "title": "Price sparklines", "description": "Compact price sparklines for up to 500 companies, keyed by the identifier sent in upper case. Identifiers that resolve to nothing are left out.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "ids", "in": "query", "description": "Comma-separated tickers, CIKs or platform keys (XADS000003). A bare ticker shared across exchanges resolves to the EDGAR issuer; address others by key.", "schema": { "type": "string" } }, { "name": "tickers", "in": "query", "description": "Alias of ids (older clients).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-company-profile", "method": "GET", "path": "/api/v1/companies/{id}", "title": "Company profile", "description": "Company profile: identity, sector, latest filing, quote, key metrics, corporate lineage. Pass `routeKey` (the ticker for an SEC registrant, else the platform key, = `cik`) or `cik` back to every /companies/{id} route; `id` is an internal record id that no route accepts. Missing values are null, never 0 or \"N/A\": `price`, `change`, `changePercent`, `prevClose`, `open` are null without a quote, and the `afterHours*` fields are null where the market has no post-market session (every Gulf exchange). Prices are in `listing_currency`; `change` is in that currency and `changePercent` in percent (1.5 = 1.5%). `marketCap`, `marketCapFull`, `volume`, `avgVolume`, `range52w`, `employees`, `float` and `ipoDate` are display strings; the numbers are `marketCapValue` (listing currency, `marketCapCurrency`) and `marketCapUsd` (at the latest stored reference rate; null without one), and the date is `ipoDateIso` (YYYY-MM-DD, or YYYY-MM / YYYY per `ipoDatePrecision`; null when no source dates the first listing). `peRatio` is the trailing P/E (fresh key metrics only), `beta` the vendor beta, `eps` trailing diluted EPS in the listing currency. `dividendYield` is the platform's trailing-12-month dividends per share (this security's dividend record, split-adjusted) ÷ latest quote, in percent (0.13 = 0.13%; null without a dividend record or quote); `statistics.dps` is that same trailing DPS and `statistics.payout` is DPS × listed-share equivalents ÷ TTM net income (not cash-flow dividends paid). Operands in `statistics.calc.dividendYield` / `.dps` / `.payout`.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company", "get_calendar", "get_monthly_revenue", "get_theme", "get_research_widget" ], "callable": true }, { "id": "get-company-logo", "method": "GET", "path": "/api/v1/companies/{id}/logo", "title": "Company logo", "description": "Company emblem image.", "groups": [ "Company Data" ], "tier": "public", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "image/*" ], "mcp_tools": [], "callable": true }, { "id": "get-financial-statements", "method": "GET", "path": "/api/v1/companies/{id}/financials", "title": "Financial statements", "description": "Standardized income statement, balance sheet and cash flow, and on request ratios, the segments & KPIs statement and the as-filed XBRL trees; each cell traceable to its source fact (fact-source). Periods are newest first by period end: `limit` periods (default 10) after skipping `period_offset`, plus the trailing-twelve-month column (TTM) in the newest window; `periods` says how much history exists (`available`) and `next_period_offset` reads the next older window (null on the last). `statements` picks the sections (default the three primary statements); `include_calc` adds each ratio cell's formula and inputs. Rows are keyed std:; columns are period labels described in period_meta. Latest restated vintage; the as-filed view is financials/as-filed. A cell absent from `values` is withheld or never reported, not zero. `cik` is the resolved company; `company_id` echoes the id sent.", "groups": [ "Financial Statements" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "period_type", "in": "query", "description": "annual, semiannual (H1 = the filer's six-month figures, H2 = FY − H1 derived) or quarterly.", "schema": { "type": "string", "enum": [ "annual", "semiannual", "quarterly" ], "default": "annual" } }, { "name": "reporting_basis", "in": "query", "description": "Quarterly / semiannual only: latest_restated (default; `individual` is the same) = the discrete quarter; as_reported = the cumulative year-to-date column as printed. A period basis — the as-filed view is financials/as-filed.", "schema": { "type": "string", "enum": [ "latest_restated", "individual", "as_reported" ], "default": "latest_restated" } }, { "name": "basis", "in": "query", "description": "Accounting basis to serve (us-gaap, ifrs-iasb, ifrs-tw, k-ifrs, ifrs-eu, cas, …). Default = the company's primary basis; other values must be one of the bases advertised in the company payload (accounting_bases) — e.g. ifrs-tw returns TSMC's Taiwan statutory statements beside its 20-F. One response never mixes bases.", "schema": { "type": "string" } }, { "name": "statements", "in": "query", "description": "Comma-separated sections: income_statement, balance_sheet, cash_flow_statement, ratios, segments_kpis, income_statement_reported, balance_sheet_reported, cash_flow_statement_reported (the *_reported trees exist for XBRL filers only), or all. Default income_statement,balance_sheet,cash_flow_statement. An unknown name is a 400.", "schema": { "type": "string", "default": "income_statement,balance_sheet,cash_flow_statement" } }, { "name": "include_calc", "in": "query", "description": "Add each ratio cell's formula and inputs (`calc`); requires ratios in `statements`. Large; default false.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Newest periods to return, by period end, after `period_offset`: 1–200, default 10. Above 200 is a 400.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 10 } }, { "name": "period_offset", "in": "query", "description": "Skip this many newest periods first: the previous reply's periods.next_period_offset. 0–1000, default 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_financials" ], "callable": true }, { "id": "get-statements-as-filed", "method": "GET", "path": "/api/v1/companies/{id}/financials/as-filed", "title": "Statements as filed", "description": "The statement exactly as the company filed it, across its whole history: every line item it ever printed (one row per printed caption — a renamed line is a new row, a discontinued line keeps its row and the period it was last used), one column per reporting period, values in units as filed. Captions, order and section headers come from the filing's own rendered statement page for inline-XBRL filings (2019→) and from its label linkbase before that; printed PDF / HTML statements serve through the same shape.", "groups": [ "Financial Statements" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "statement", "in": "query", "description": "income_statement | comprehensive_income | balance_sheet | balance_sheet_parenthetical | cash_flow_statement | equity | all (all = every statement the company has, empty ones omitted).", "schema": { "type": "string", "enum": [ "income_statement", "comprehensive_income", "balance_sheet", "balance_sheet_parenthetical", "cash_flow_statement", "equity", "all" ] }, "required": true }, { "name": "period_type", "in": "query", "description": "annual, semiannual or quarterly.", "schema": { "type": "string", "enum": [ "annual", "semiannual", "quarterly" ], "default": "annual" } }, { "name": "reporting_basis", "in": "query", "description": "Quarterly / semiannual: individual (default) = the discrete period; as_reported = the cumulative year-to-date column as printed.", "schema": { "type": "string", "enum": [ "individual", "as_reported" ], "default": "individual" } }, { "name": "vintage", "in": "query", "description": "original = each period from the filing the company made for it (what it first reported); latest = each period from the newest filing that carries it (restated comparatives).", "schema": { "type": "string", "enum": [ "original", "latest" ], "default": "original" } }, { "name": "format", "in": "query", "description": "json, csv or xlsx (csv/xlsx stream a download; with statement=all, one block or sheet per statement, xlsx adds a Provenance sheet).", "schema": { "type": "string", "enum": [ "json", "csv", "xlsx" ], "default": "json" } }, { "name": "from", "in": "query", "description": "First period end, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last period end, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Latest N columns in range, 1–200 (else 400); adds `window`. Omitted = every column.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_financials_as_filed" ], "callable": true }, { "id": "get-fact-provenance", "method": "GET", "path": "/api/v1/companies/{id}/fact-source", "title": "Fact provenance", "description": "Provenance for one cell: the fact(s) (or the printed cell and page for PDF-sourced issuers), the filing accession or document reference, and the arithmetic behind derived values.", "groups": [ "Financial Statements" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "statement", "in": "query", "description": "Required. Which statement the row belongs to; an unknown one is a 404.", "schema": { "type": "string", "enum": [ "income_statement", "balance_sheet", "cash_flow_statement", "segments_kpis", "supply_chain" ] }, "required": true }, { "name": "key", "in": "query", "description": "The row key exactly as /financials returned it: std: (std:revenue), a raw XBRL tag (us-gaap:Revenues), a segment row seg::::::, a KPI row kpi::, or a supply-chain metric rel:::::: (provenance.fact_source_key on /supply-chain).", "schema": { "type": "string" }, "required": true }, { "name": "end_date", "in": "query", "description": "The column's period end date, YYYY-MM-DD (from period_meta).", "schema": { "type": "string" }, "required": true }, { "name": "period_type", "in": "query", "description": "Must match the /financials call being cited.", "schema": { "type": "string", "enum": [ "annual", "semiannual", "quarterly" ], "default": "annual" } }, { "name": "basis", "in": "query", "description": "Must match the reporting_basis of the /financials call being cited.", "schema": { "type": "string", "enum": [ "individual", "as_reported" ], "default": "individual" } }, { "name": "accounting_basis", "in": "query", "description": "Accounting basis the cited cell was shown under (see financials `basis`); default = primary.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_fact_source" ], "callable": true }, { "id": "get-stock-prices", "method": "GET", "path": "/api/v1/companies/{id}/prices", "title": "Stock prices", "description": "Daily OHLCV bars of the company's listed security (the share class of a ticker), in its listing `currency`. Bars run from the first trading day of `range` to the latest; `lookback` adds earlier bars for moving averages. `coverageFrom` is the first day held; `note` says when the history starts after the range's first day or no bar falls inside it. Bar times `t` are epoch ms at UTC midnight. An unknown company is a 404.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "Window of bars served: from the range's first day (1M = 31 days back, YTD = 1 January) to the latest bar; ALL is the whole history. `rangeFrom` echoes the first day; `displayFrom` is the epoch ms of the first bar inside the range.", "schema": { "type": "string", "enum": [ "1M", "3M", "6M", "YTD", "1Y", "2Y", "5Y", "ALL" ], "default": "1Y", "x-case-insensitive": true } }, { "name": "lookback", "in": "query", "description": "Bars to add before the range's first day, e.g. 200 to draw a 200-day moving average from the first bar. Default 0: only bars inside the range. `lookbackBars` says how many were added.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-company-filings", "method": "GET", "path": "/api/v1/companies/{id}/filings", "title": "Company filings", "description": "The company's document index: SEC filings (accession numbers) and documents published outside EDGAR (exchange disclosures, IR publications; their document reference in `accessionNumber`, `documentKind` pdf), newest filing date first, undated documents last. Page with `limit` / `offset` (the reply's `nextOffset`; also `total`, `hasMore`) or with `page` / `pageSize` (`totalPages`); `typeCounts` always counts the whole unfiltered index.", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–100 (default 50). With `offset`, replaces page/pageSize.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip: the previous reply's `nextOffset`.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "page", "in": "query", "description": "1-based page number, default 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "description": "Rows per page, 1–100, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "types", "in": "query", "description": "Comma-separated exact form codes, e.g. 10-K,10-Q,8-K or FS-A,FS-Q (typeCounts lists the company's).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_filings" ], "callable": true }, { "id": "get-filing-detail", "method": "GET", "path": "/api/v1/companies/{id}/filings/{accession}", "title": "Filing detail", "description": "One listed document. By default the document itself: an SEC filing's primary document as sanitized HTML, or a source document's stored PDF, HTML, announcement, package or media (`accession` = the SEC accession or the document reference as the filings index lists it, e.g. DFM-EMAAR-2026Q2-FS). With `format=text`, its text as JSON: `{ document: { id, cik, title, form, type, date, source_url, pages, part, slides? }, parts? (SEC: the submission's readable documents), text_source (html | sgml_text | json | pdf_extracted | stored_extraction | ocr), stored_as?, page_from, page_to, pages_in_text, pages_without_text?, text, offset, next_offset, total_chars, truncated?, note?, source }`. Paged documents mark each page \"[page N]\" (the PDF page, the filing's own HTML page breaks, or the slide). A document with no text to read (slide images, an un-OCR'd scan, a recording) answers 200 with `text: null` and `text_unavailable: { reason, detail, page_images?, document_route }`; text is never reconstructed.", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "accession", "in": "path", "required": true, "description": "SEC accession number (0001045810-25-000023) or source-document reference (EMAARIR-2026Q2-PRES), as the filings index lists it.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "`text` = the document's text as paged JSON (see above); omit for the document itself.", "schema": { "type": "string", "enum": [ "text" ] } }, { "name": "part", "in": "query", "description": "format=text, SEC filings: one document of the submission by its type (EX-99.1) or file name, from `parts`; default the primary document.", "schema": { "type": "string" } }, { "name": "page_from", "in": "query", "description": "format=text: first page to read (paged documents).", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "page_to", "in": "query", "description": "format=text: last page to read (default the last).", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "offset", "in": "query", "description": "format=text: character offset into the selected pages; the previous `next_offset`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "max_chars", "in": "query", "description": "format=text: characters to return, 1,000–200,000.", "schema": { "type": "integer", "minimum": 1000, "maximum": 200000, "default": 50000 } } ], "request_body": null, "response_types": [ "text/html", "application/json" ], "mcp_tools": [ "get_document_text" ], "callable": true }, { "id": "get-filing-sections", "method": "GET", "path": "/api/v1/companies/{id}/filing-notes", "title": "Filing sections", "description": "Every parsed filing (10-K, 10-Q, 20-F, DEF 14A, S-1 and exchange-lane reports) with its narrative sections — Business, Risk Factors, MD&A, … — newest filing first, sections in item order; section text at /filing-notes/{sectionId}. Paged by filing: `total`, `limit`, `offset`, `hasMore`, `nextOffset`; `filingTypes` and `sectionTypes` count what the whole index holds (before filters), and `emptyReason` says why an empty page is empty. The index lists what has been parsed, not everything filed.", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Filings per page, 1–500 (above 500 is a 400).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 10 } }, { "name": "offset", "in": "query", "description": "Filings to skip: the previous reply's `nextOffset`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "document", "in": "query", "description": "One filing: its accession number (dashed or not) or document reference, as listed.", "schema": { "type": "string" } }, { "name": "types", "in": "query", "description": "Comma-separated filing form codes, e.g. 10-K,10-Q or FS-A,AR (case-insensitive).", "schema": { "type": "string" } }, { "name": "section_types", "in": "query", "description": "Comma-separated section types, e.g. item_7,item_1a or fs_note (at most 20); a filing keeps only these sections and drops out when none is left.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_filing_sections" ], "callable": true }, { "id": "get-note-tables-index", "method": "GET", "path": "/api/v1/companies/{id}/filing-notes/tables", "title": "Note tables index", "description": "Tabular filing notes: families with their served tables (gate verdicts, no grid) and the documents they come from. Paged by table, in index order (family by family, newest first within a family): without `view`, the first `limit` tables (default 100) with `total`, `limit`, `offset`, `hasMore` and `nextOffset`; read on with `offset` = `nextOffset`. `family` and/or `document` narrow the tables (every match when `limit` is omitted). `view=summary` is one line per family (table count, first and last period) plus the documents, the smallest answer; `view=full` is every table in one reply, not paged (large: 3 MB for a bank with twenty years of notes). One table's grid: /filing-notes/tables/{tableId}; one family over time: /filing-notes/series.", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`summary`: one line per family plus the documents. `full`: every table in one reply. Omit for the paged list of tables.", "schema": { "type": "string", "enum": [ "summary", "full" ] } }, { "name": "family", "in": "query", "description": "Only this family's tables, the key exactly as listed.", "schema": { "type": "string" } }, { "name": "document", "in": "query", "description": "Only this document's tables (doc_ref).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Tables per page, 1–200 (above 200 is a 400); not with `view`.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "offset", "in": "query", "description": "Tables to skip: the previous reply's `nextOffset`; not with `view`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "kind", "in": "query", "description": "Which tables: `notes` (the notes to the statements, the default), `presentations` (investor-deck tables) or `guidance` (deck guidance tables).", "schema": { "type": "string", "enum": [ "notes", "presentations", "guidance" ], "default": "notes" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_note_tables" ], "callable": true }, { "id": "get-note-family-series", "method": "GET", "path": "/api/v1/companies/{id}/filing-notes/series", "title": "Note family series", "description": "Canonical time series of one note family across filings (lines × period ends, each point citing its document; reported vs comparative; later vintages; quarterly cadence derives Q4 for flow lines).", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "family", "in": "query", "description": "Required. An UPPER_SNAKE notes family, e.g. INVENTORY_COMPOSITION. Investor-presentation families have no series (400): read their tables via /filing-notes/tables?kind=presentations&family=.", "schema": { "type": "string" }, "required": true }, { "name": "cadence", "in": "query", "description": "annual (default) or quarterly.", "schema": { "type": "string", "enum": [ "annual", "quarterly" ], "default": "annual" } }, { "name": "from", "in": "query", "description": "First period end, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last period end, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Latest N periods in range, 1–200; adds `series.window`.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_note_tables" ], "callable": true }, { "id": "get-note-table", "method": "GET", "path": "/api/v1/companies/{id}/filing-notes/tables/{tableId}", "title": "Note table", "description": "One note table as filed: columns, rows, cells with source evidence and gate results.", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "tableId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_note_tables" ], "callable": true }, { "id": "get-section-text", "method": "GET", "path": "/api/v1/companies/{id}/filing-notes/{sectionId}", "title": "Section text", "description": "Plain text of one filing section, read in windows: `max_chars` characters (default 50,000) from `offset`, ending at a paragraph or line break near the end. As text/plain (default) the window's place is in the headers `X-Text-Offset`, `X-Text-Total-Chars` and `X-Text-Next-Offset` (empty at the end of the text); with `format=json` the reply is `{ cik, sectionId, text, offset, maxChars, totalChars, hasMore, nextOffset }`. Read on with `offset` = the next offset until it is empty / null.", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "sectionId", "in": "path", "required": true, "description": "Numeric section id from /filing-notes.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Character offset to start at: the previous window's next offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "max_chars", "in": "query", "description": "Characters per window, 1,000–200,000.", "schema": { "type": "integer", "minimum": 1000, "maximum": 200000, "default": 50000 } }, { "name": "format", "in": "query", "description": "`text` (default): text/plain; `json`: the window and its offsets as JSON.", "schema": { "type": "string", "enum": [ "text", "json" ], "default": "text" } } ], "request_body": null, "response_types": [ "text/plain" ], "mcp_tools": [ "get_section_text" ], "callable": true }, { "id": "get-company-8-k-events", "method": "GET", "path": "/api/v1/companies/{id}/events", "title": "Company 8-K events", "description": "The company's 8-K items (an exchange issuer's disclosures classified the same way, with the document reference in `accessionNumber`): one row per item, newest filing first, undated rows last (`sort=oldest` reverses the dates). Rows carry no family field: filter with `family`. The reply carries `total` (after filters), `unfilteredTotal`, `limit`, `offset`, `hasMore` and `nextOffset`.", "groups": [ "8-K Events" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–500. Omitted = every matching row.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "description": "Rows to skip: the previous reply's `nextOffset`. Default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "family", "in": "query", "description": "One or more event families, comma-separated: keeps items whose SEC item code defines the family (5.02 leadership, 2.02 earnings, 1.01 agreement, 2.01 mna, 5.07 governance_vote, …) or whose span-verified facts belong to it. dividend, buyback, guidance, stock_split and legal_regulatory have no item of their own and match only extracted facts. Values: dividend, stock_split, guidance, earnings, mna, debt_financing, equity_financing, buyback, restatement_non_reliance, cyber_incident, restructuring, impairment, leadership, governance_vote, agreement, legal_regulatory, listing_compliance, other.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "2–200 characters, case-insensitive: item names and codes, and the headline, summary, quote and subject of the item's extracted facts.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "First filing date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last filing date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "description": "Filing-date order; undated rows sort last either way.", "schema": { "type": "string", "enum": [ "newest", "oldest" ], "default": "newest" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_events" ], "callable": true }, { "id": "get-8-k-item-text", "method": "GET", "path": "/api/v1/companies/{id}/events/{accession}", "title": "8-K item text", "description": "The extracted plain text of one 8-K item, or of an exchange disclosure by its document reference (e.g. DFM-EMAAR-20261013-DISC, as the events index lists it). With `item` omitted the item is chosen: the filing's only coded item, else the only one left once Item 9.01 (exhibits) is set aside, else its uncoded item; when several substantive items remain the reply is a 400 (`code` missing_parameter, `param` item) listing them in `items`. An accession the company does not list is a 404 (`code` not_found); a listed exchange document with no extracted item text is a 404 whose `readWith` names the document text route. Paged: `max_chars` characters from `offset`. `format=text` (default) answers text/plain with the window in the headers X-Item-Code, X-Text-Offset, X-Text-Total-Chars and X-Text-Next-Offset (empty at the end); `format=json` answers { cik, accession, item, itemName, itemPicked, items, text, offset, maxChars, totalChars, hasMore, nextOffset }.", "groups": [ "8-K Events" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "accession", "in": "path", "required": true, "description": "SEC accession number, e.g. 0001045810-25-000023.", "schema": { "type": "string" } }, { "name": "item", "in": "query", "description": "8-K item code from the events index (e.g. 2.02, 1.01). Omit it to have the item chosen as described above.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Character offset: the previous reply's next offset. Default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "max_chars", "in": "query", "description": "Characters per reply, 1,000–200,000.", "schema": { "type": "integer", "minimum": 1000, "maximum": 200000, "default": 50000 } }, { "name": "format", "in": "query", "description": "text = text/plain (default); json = the window and item as JSON.", "schema": { "type": "string", "enum": [ "text", "json" ], "default": "text" } } ], "request_body": null, "response_types": [ "text/plain" ], "mcp_tools": [ "get_event_text" ], "callable": true }, { "id": "get-segment-revenue", "method": "GET", "path": "/api/v1/companies/{id}/segment-revenue", "title": "Segment revenue", "description": "The latest served revenue breakdown on the first business axis that has one (product, then operating segment, brand, channel), from the gated segment layer, with its source. A filer with no revenue breakdown gets its segment top line (premiums earned, net interest income, lease income).", "groups": [ "Financial Statements" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_segment_revenue" ], "callable": true }, { "id": "get-regional-revenue", "method": "GET", "path": "/api/v1/companies/{id}/regional-revenue", "title": "Regional revenue", "description": "The latest served revenue breakdown by geography, from the gated segment layer, with its source.", "groups": [ "Financial Statements" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_segment_revenue" ], "callable": true }, { "id": "get-supply-chain", "method": "GET", "path": "/api/v1/companies/{id}/supply-chain", "title": "Supply chain", "description": "Disclosed suppliers, customers and competitors with source-backed metrics. Partners are not served (owner, 2026-11-12): a partnership cannot be evidenced reliably, unlike a supplier or customer. Every metric states whose figure it is (`whose`), the measurement period, the filing (`provenance.accession`) and, when withheld, the reason codes — cite those, never a bare percentage. `coverage` is the disclosed-customer share of the company's own revenue for one filing and period (never an estimate of the whole network). Anonymous customers (\"Customer One\") are filing-scoped and never unified across filings; labels a later report superseded are omitted unless `include_historical=true`. Every relationship carries `evidence_basis`: filed_structured (the filer's XBRL facts), company_published (a supplier/customer/partner list the company itself publishes), human_certified (filing text, human-audited), model_extracted (filing text incl. 8-K Item 1.01, quote-anchored, model-extracted under an active serving policy) call_transcript (an earnings-call passage) or analyst_curated (a competitor chosen by Astreus analysts, not named in any filing; it carries `curation` {rank, arena, rationale, products: [{member, label, arena, rationale, strength}] — the product lines it competes in, by the revenue member the company files, strength 3 major, 2 medium, 1 low, null ungraded —, sources, curated_at}, `direction` curated and no metrics) — cite it as such. When a company has a curated competitor list, that list replaces its filing-derived competitors on its own page only. Curated supply chain: any supplier or customer may carry `supply_curation` {items: [{origin (subject = this company's own curated list, counterparty = the other company's list, shown here with the role flipped), curated_on {cik, name}, member and label (the curating company's revenue member, null = company-wide), product_rank, flow (what is supplied or bought), rationale, strength (dependence of that line on the counterparty: 3 critical, 2 material, 1 minor), evidence_kind and sources [{kind: subject_document, counterparty_document, earnings_call or credible_report; title; url; date}], figure ({basis: reported, text, value, unit pct/usd/units, of, period, source} or null)}], curated_at}. It sits beside the disclosures and never changes a disclosed relationship's basis or metrics; a curated supplier or customer no filing lane holds has evidence_basis analyst_curated, direction curated and no metrics. A figure is a number the cited source states: reported, never a disclosed metric, never in `coverage`. A curated customer may be a segment rather than an entity: other_party.kind customer_segment, counterparty_id 0, `segment` {code (e.g. consumer.gaming), label, audience}. When a company has its own curated supply chain, that list is its supply chain: suppliers and customers it does not map to a business unit are not returned for it (partners and competitors are unaffected; other companies keep their own record). With `include_estimates=true`, metrics of state `estimate` (`counterparty_revenue_pct_est`) attribute a counterparty's undisclosed top-customer share by rule; they are estimates, never disclosed figures, and never enter `coverage`. Counterparties of kind named_unlinked are named in the filing but matched to no company page. `status` distinguishes not_processed, no_disclosures_found, partial and ok; `as_of` returns what was public through that UTC date under today's rules.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "customers, suppliers, competitors or all (default).", "schema": { "type": "string", "enum": [ "customers", "suppliers", "competitors", "all" ], "default": "all" } }, { "name": "quantified_only", "in": "query", "description": "true = only relationships with at least one eligible metric.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "as_of", "in": "query", "description": "YYYY-MM-DD: public information through the end of that UTC date.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "company_exposure (default; the company's own metric), relationship_exposure (the other party's metric) or name. Metrics missing sort last, ties by edge key.", "schema": { "type": "string", "enum": [ "company_exposure", "relationship_exposure", "name" ], "default": "company_exposure" } }, { "name": "limit", "in": "query", "description": "Relationships per page, 1–5000, default 50 (5000 reads a company's whole set at once, as the CSV export does); page on with `cursor`.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor bound to all filters and the data revision; restart on 409.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Counterparty name or ticker contains.", "schema": { "type": "string" } }, { "name": "named_only", "in": "query", "description": "Exclude anonymous and grouped counterparties.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "country", "in": "query", "description": "Two-letter country code.", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "description": "Exact sector name.", "schema": { "type": "string" } }, { "name": "display_currency", "in": "query", "description": "Three-letter display currency; original amounts retained; historical FX unavailable.", "schema": { "type": "string" } }, { "name": "include_historical", "in": "query", "description": "true = also return filing-scoped anonymous labels that a later report superseded.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "include_estimates", "in": "query", "description": "true = include estimate-tier metrics (state=estimate), attributed by rule, never disclosed figures.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_supply_chain" ], "callable": true }, { "id": "get-supply-chain-relationship", "method": "GET", "path": "/api/v1/companies/{id}/supply-chain/{edgeKey}", "title": "Supply-chain relationship", "description": "One relationship in full: current metrics, every served measurement period (eligible and withheld with reasons) and the evidence rows behind it (discloser, accession, XBRL context, quote locator). An analyst-curated competitor (evidence_basis analyst_curated) returns its `curation` with empty history and evidence; a curated supplier or customer returns its `supply_curation` (with empty history and evidence when no filing lane holds it). The edge must belong to the company in the path.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "edgeKey", "in": "path", "required": true, "schema": { "type": "string" }, "description": "edge_key from the supply-chain list." }, { "name": "as_of", "in": "query", "description": "YYYY-MM-DD: public information through the end of that UTC date.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_supply_chain" ], "callable": true }, { "id": "get-company-assets-map", "method": "GET", "path": "/api/v1/companies/{id}/assets", "title": "Company assets (map)", "description": "The company's physical assets as GeoJSON — buildings, malls, hotels, toll gates, plants, ports, cables, data centres — each with the company's role on it (owner, operator, developer, concessionaire, grantor, tenant, partner…) and share where disclosed, lifecycle status (announced, under_construction, suspended, operating, …) as of `as_of`, the declared location precision (`precision` exact | approximate | locality | region | country, with `precision_m` the error radius in metres — draw it, never a pin of false certainty), the registry `layer` that draws it and its label `anchor_lon`/`anchor_lat`. Only reviewed, sourced assets appear; cite the per-asset sources from /geo/features/{key}. Pilot coverage, starting with curated UAE issuers: an empty `features` list means no reviewed assets yet, not that the company has none. `attribution` lists what the licences require you to display (e.g. © OpenStreetMap contributors for ODbL geometry). The map view is paged by feature: `limit` features (default 50) from `offset`, with `total`, `limit`, `offset`, `hasMore` and `nextOffset`; `bbox`, `layers` and `counts` describe the whole map, and `former` (assets no longer held) comes on the first page only, up to `limit` of them (`formerTotal` counts them all; page them with view=attributes&holding=former).", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "as_of", "in": "query", "description": "YYYY-MM-DD: the map as it stood that day — assets not yet announced drop out and only parties valid on that day count. Default today.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`geojson` (default): the map, paged by feature. `attributes`: no geometry — `summary` counts (level, kind, country, status) and one page of `assets`, each with `geometry_licence` and `location` (null with `location_withheld` when the licence is share-alike or unrecorded). The attributes filters (kind, status, level, q, country, holding) are a 400 on the map view.", "schema": { "type": "string", "enum": [ "geojson", "attributes" ], "default": "geojson" } }, { "name": "kind", "in": "query", "description": "attributes: asset kind codes, comma-separated, at most 30.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "attributes: lifecycle statuses, comma-separated.", "schema": { "type": "string" } }, { "name": "level", "in": "query", "description": "attributes: register level, asset | component | all (default all).", "schema": { "type": "string", "enum": [ "asset", "component", "all" ] } }, { "name": "q", "in": "query", "description": "attributes: words in the name.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "attributes: ISO alpha-2 codes, comma-separated.", "schema": { "type": "string" } }, { "name": "holding", "in": "query", "description": "attributes: current (default) = assets held now; former = assets no longer held.", "schema": { "type": "string", "enum": [ "current", "former" ] } }, { "name": "limit", "in": "query", "description": "Page size, default 50: map view 1–5,000 features; attributes 1–200 rows. Above the maximum is a 400.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip: map view, the previous `nextOffset`; attributes, the previous `next_offset`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "consolidated", "in": "query", "description": "1 adds the assets the company holds through its listed subsidiaries, each with the subsidiary it comes through and the stake.", "schema": { "type": "string", "enum": [ "1", "0" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company_assets" ], "callable": true }, { "id": "get-map-layers", "method": "GET", "path": "/api/v1/geo/layers", "title": "Map layers", "description": "The map layer registry: every layer your plan can see, its declarative symbology (colour token, marker shape, extrusion, label), the asset kinds it draws, zoom range, licence and attribution. A new layer is a registry row — render whatever this returns.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_asset_companies" ], "callable": true }, { "id": "get-countries-with-mapped-assets", "method": "GET", "path": "/api/v1/geo/countries", "title": "Countries with mapped assets", "description": "The countries that have mapped assets on some layers, with how many each (`layer`, ISO alpha-2 `country`, `count`) — what a per-country overlay lists. Only reviewed assets count.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "layers", "in": "query", "description": "Required. Comma-separated layer codes from /geo/layers, at most 50.", "schema": { "type": "string" }, "required": true } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_asset_companies" ], "callable": true }, { "id": "get-assets-in-an-area", "method": "GET", "path": "/api/v1/geo/features", "title": "Assets in an area", "description": "Served assets inside a bounding box, or in some countries, as GeoJSON (the GeoJSON path for global layers; same feature properties as /companies/{id}/assets without the company role fields). `truncated` is true when more features exist than `limit` — narrow the box, the countries or the layers. Pilot coverage: only reviewed assets appear.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "bbox", "in": "query", "description": "west,south,east,north in degrees (EPSG:4326); at most 60° per side; split boxes that cross the antimeridian. Required unless `countries` is given.", "schema": { "type": "string" } }, { "name": "countries", "in": "query", "description": "Comma-separated ISO 3166-1 alpha-2 codes (e.g. AE,SA), at most 60: only assets in these countries, wherever they are — with no `bbox`, the whole country.", "schema": { "type": "string" } }, { "name": "layers", "in": "query", "description": "Comma-separated layer codes from /geo/layers, at most 50 (default: every feature layer).", "schema": { "type": "string" } }, { "name": "cik", "in": "query", "description": "Only this company's assets (SEC CIK or platform key).", "schema": { "type": "string" } }, { "name": "as_of", "in": "query", "description": "YYYY-MM-DD; default today.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1–5000, default 2000; with view=attributes the page size, 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 2000 } }, { "name": "view", "in": "query", "description": "`attributes`: no geometry — `summary` counts and one page of `assets` with `geometry_licence` and `location` (withheld when the licence is share-alike or unrecorded); works with `countries` or `bbox`.", "schema": { "type": "string", "enum": [ "attributes" ] } }, { "name": "kind", "in": "query", "description": "attributes: asset kind codes, comma-separated, at most 30.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "attributes: lifecycle statuses, comma-separated.", "schema": { "type": "string" } }, { "name": "level", "in": "query", "description": "attributes: register level, asset | component | all (default all).", "schema": { "type": "string", "enum": [ "asset", "component", "all" ] } }, { "name": "q", "in": "query", "description": "attributes: words in the name.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "attributes: rows to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "search_assets" ], "callable": true }, { "id": "get-asset-detail", "method": "GET", "path": "/api/v1/geo/features/{key}", "title": "Asset detail", "description": "One asset in full: kind, status and dated lifecycle, location precision, geometry type, bbox, area or length, kind-specific attributes, every party with role, share and validity, containment (parent, children), typed links to other assets, external identifiers with links (OpenStreetMap, Wikidata, Overture GERS) and the sources behind each fact with what each supports (existence, location, ownership, attributes, lifecycle).", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable asset key from the `key` property of an assets / features response, e.g. ae.dubai.emaar.burj-khalifa." }, { "name": "as_of", "in": "query", "description": "YYYY-MM-DD: status as of that day; default today.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`attributes`: `anchor` and `bbox` become `location` and `extent`, both null with `location_withheld` when the licence is share-alike or unrecorded.", "schema": { "type": "string", "enum": [ "attributes" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_asset" ], "callable": true }, { "id": "get-asset-alt-data", "method": "GET", "path": "/api/v1/geo/features/{key}/data", "title": "Asset alt data", "description": "Alternative data collected on one asset (construction progress, satellite change) as time series. An unknown asset key is a 404; a `view` other than `series` is a 400.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable asset key, e.g. ae.dubai.emaar.burj-khalifa." }, { "name": "view", "in": "query", "description": "`series`: each series names its sources (publisher, link, licence) and the attribution they require; leaves out toll-gate traffic and rows that are non-commercial or cite no source.", "schema": { "type": "string", "enum": [ "series" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_asset" ], "callable": true }, { "id": "get-live-vessels", "method": "GET", "path": "/api/v1/tracking/vessels", "title": "Live vessels", "description": "Live vessel positions (AIS) inside a bounding box: the last report of every vessel heard in the last 24 hours, newest first, as column-oriented rows — `fields` names the columns (mmsi, lon, lat, cog, sog, heading, category, name, flag, ageS, navStatus, lengthM). `ageS` is the age of each position: a live map shows last-known positions. `sources` lists each feed with its coverage and health — coverage is regional until a global satellite feed is licensed, so an empty sea means not heard, not empty (`coverageNote`). `attribution` lists the credits to display. Paged newest first: `limit`, `offset`, `hasMore`, `nextOffset` (`truncated` is the same as `hasMore`); a whole viewport for a map is one call with `limit=15000`.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "bbox", "in": "query", "description": "west,south,east,north in degrees; default the world.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Comma-separated: tanker, cargo, passenger, fishing, service, high_speed, pleasure, military, other, unknown.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–20000, default 2000.", "schema": { "type": "integer", "minimum": 1, "maximum": 20000, "default": 2000 } }, { "name": "offset", "in": "query", "description": "Rows to skip (the previous `nextOffset`), 0–200000, default 0. Positions move between calls, so a later page can repeat or miss a vessel.", "schema": { "type": "integer", "minimum": 0, "maximum": 200000, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-vessel-detail", "method": "GET", "path": "/api/v1/tracking/vessels/{mmsi}", "title": "Vessel detail", "description": "One vessel: identity (IMO, name, call sign, AIS type, flag from its MMSI, length and beam), voyage as broadcast (destination, ETA, draught), last position with age, its path over the last 24 hours (`track.coordinates`: lon, lat, epoch seconds), recent port calls with dwell and draught in/out, and earlier identities (renames, re-flags). 404 when not heard in 24 hours.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "mmsi", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Maritime Mobile Service Identity, 1–9 digits." } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-live-aircraft", "method": "GET", "path": "/api/v1/tracking/aircraft", "title": "Live aircraft", "description": "Live aircraft positions (ADS-B / MLAT) inside a bounding box: every aircraft heard in the last 10 minutes, newest first, as column-oriented rows — `fields` names the columns (icao24, lon, lat, track, gs, alt, onGround, callsign, type, registration, airline, ageS, military, vrate). Positions refresh every one to ten minutes depending on type; extrapolate along `track` at `gs` for short gaps. Aircraft in the FAA LADD and privacy-address programmes are never served. Paged newest first: `limit`, `offset`, `hasMore`, `nextOffset` (`truncated` is the same as `hasMore`); an empty sky means not heard (`coverageNote`, `sources`).", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "bbox", "in": "query", "description": "west,south,east,north in degrees; default the world.", "schema": { "type": "string" } }, { "name": "military", "in": "query", "description": "1 = military aircraft only; 0 (default) = all.", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ], "default": "0" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–20000, default 2000.", "schema": { "type": "integer", "minimum": 1, "maximum": 20000, "default": 2000 } }, { "name": "offset", "in": "query", "description": "Rows to skip (the previous `nextOffset`), 0–200000, default 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 200000, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-aircraft-detail", "method": "GET", "path": "/api/v1/tracking/aircraft/{icao24}", "title": "Aircraft detail", "description": "One aircraft by its 24-bit ICAO address: registration, type, owner/operator, airline (with its company `cik` when the airline is a covered company), last position, the current flight leg (origin and destination airports, take-off and landing times, highest altitude) with its path (`path.coordinates`: lon, lat, altitude m, epoch seconds), and recent legs. 404 when not heard in 10 minutes.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "icao24", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ICAO 24-bit address, 6 hex digits (e.g. 896123)." } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-chokepoint-transits", "method": "GET", "path": "/api/v1/tracking/chokepoints", "title": "Chokepoint transits", "description": "Maritime chokepoints (Hormuz, Bab-el-Mandeb, Suez, Panama, Singapore Strait, Gibraltar, Dover, Skagen, Øresund, Great Belt, Gulf of Finland, Cape Agulhas) with their crossing lines and the vessel transits detected: today, last 7 days by direction and vessel category, and a daily series. Each gate says whether the feeds cover it (`covered`, `coverage` { status covered | partial | none, daysWithTransits7d, firstDayWithTransits, note }): covered = transits recorded on each of the last 7 complete UTC days. Where not covered, `transitsToday`, `transits7d` and zero days in `daily` are null (unknown, not zero) and `recorded` { today, last7d } holds what was seen, a lower bound. Covered counts are what the feeds heard, so a feed that hears part of a strait undercounts it.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "days", "in": "query", "description": "1–90, default 30.", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-port-activity", "method": "GET", "path": "/api/v1/tracking/ports/{key}", "title": "Port activity", "description": "Vessel activity at a port (map feature key from /geo/features, e.g. port.wpi.48276 — Jebel Ali): vessels in port now (tankers, cargo), arrivals and departures over 24 hours and 7 days, median dwell over 30 days, the vessels in port and recent departures. A call opens when a vessel is slow inside the port's zone for 10 minutes. `covered` is true when the feeds reported a vessel there in the last 24 hours; otherwise (`coverage.status` lapsed, with `lastActivityAt`) the counts are null (unknown, not zero) and `recorded` holds what was seen. 404 when no call was recorded there in 30 days.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Port feature key." } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-airport-activity", "method": "GET", "path": "/api/v1/tracking/airports/{key}", "title": "Airport activity", "description": "Flight activity at an airport (map feature key, e.g. airport.omdb — Dubai): departures and arrivals detected in the last 24 hours with the flights.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Airport feature key." } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-live-feeds", "method": "GET", "path": "/api/v1/tracking/sources", "title": "Live feeds", "description": "The live feeds served, per domain (vessel, aircraft): publisher, licence, credit line, coverage in words, and whether each is delivering now.", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-company-live-fleet", "method": "GET", "path": "/api/v1/companies/{id}/fleet", "title": "Company live fleet", "description": "The company's aircraft in the air now: each airline designator linked to the company (its own airline and consolidated subsidiaries, with the basis of the link), live aircraft and flights started in the last 24 hours per airline, and the live aircraft as column-oriented rows (same fields as /tracking/aircraft).", "groups": [ "Geo & Assets" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-capital-structure", "method": "GET", "path": "/api/v1/companies/{id}/capital-structure", "title": "Capital structure", "description": "Annual cash, total debt and total equity per fiscal year end, oldest first (`capital_structure.series[]`: period, cash, debt, equity). cash = cash and short-term investments, else cash; debt = short-term + long-term debt. `capital_structure` is null when the company has none.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company" ], "callable": true }, { "id": "get-overview-series", "method": "GET", "path": "/api/v1/companies/{id}/overview-series", "title": "Overview series", "description": "Overview chart series: annual revenue, diluted EPS and free cash flow, plus the income-statement subtotals (revenue, gross profit, operating, pretax, net) per fiscal year and discrete quarter that feed the revenue-to-profit waterfall, and debt / free cash flow / cash per period for the debt-coverage chart.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company" ], "callable": true }, { "id": "get-monthly-revenue", "method": "GET", "path": "/api/v1/companies/{id}/monthly-revenue", "title": "Monthly revenue", "description": "Regulator-mandated monthly revenue (Taiwan issuers), current vintage, as filed, with the open-data licence attribution. 404 when the company has no monthly mandate.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_monthly_revenue" ], "callable": true }, { "id": "get-dividends", "method": "GET", "path": "/api/v1/companies/{id}/dividends", "title": "Dividends", "description": "Cash dividend history by ex-date: as-paid and split-adjusted amounts, trailing-12-month total, change vs the prior payment, and each payment's yield AT THE TIME on two price bases — `yieldAtExDatePct` (TTM ÷ the last split-adjusted close before the ex-date) and `yieldPeriodAvgPct` (TTM ÷ the average close from the previous ex-date to the day before this one). `summary` carries the current trailing and indicated yield, cadence and DPS growth; `yieldSeries` is the month-end trailing-yield history. `events` are ordered by ex-date, oldest first by default (`order=desc` for newest first); `from` / `to` (ex-date), `limit` and `offset` window `events` and add `total`, `limit`, `offset`, `hasMore` and `nextOffset`, while `summary`, `announced`, `undated` and `yieldSeries` always describe the whole record. Yields are in percent (3.2 = 3.2%).", "groups": [ "Financial Statements" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`declared`: exchange-notice and filing rows with their proof only — no vendor rows, yields, prices or split-adjusted amounts; adds `omittedVendorRows`.", "schema": { "type": "string", "enum": [ "declared" ] } }, { "name": "order", "in": "query", "description": "Ex-date order of `events`.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "from", "in": "query", "description": "First ex-date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last ex-date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Events per page, 1–500. Omitted = every event.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "description": "Events to skip: the previous reply's `nextOffset`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_dividends" ], "callable": true }, { "id": "get-earnings-calendar", "method": "GET", "path": "/api/v1/companies/{id}/calendar", "title": "Company events calendar", "description": "The company's dated disclosure events, newest first: 8-K items on their event date (earnings releases, dividend declarations, leadership changes, annual meetings, other filing events) and dividend ex-dates, each with kind, item code, label, accession and severity; `isEarnings` marks 8-K Item 2.02 rows. Also `fiscalYearEnd`. Paged, newest event date first: `limit` (default 100) and `offset`; the body carries `total`, `limit`, `offset`, `hasMore` and `nextOffset` (a large issuer holds 700+ events). No scheduled or estimated results dates: use /earnings/calendar?cik=.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Events per page, 1–500, default 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "description": "Events to skip (the previous `nextOffset`), default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "from", "in": "query", "description": "First event date, YYYY-MM-DD (inclusive).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Last event date, YYYY-MM-DD (inclusive).", "schema": { "type": "string" } }, { "name": "earnings", "in": "query", "description": "true = only 8-K Item 2.02 (results) events.", "schema": { "type": "boolean", "default": false } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar" ], "callable": true }, { "id": "get-earnings-calendar-all-companies", "method": "GET", "path": "/api/v1/earnings/calendar", "title": "Earnings calendar (all companies)", "description": "Results dates in a window, worldwide: issuer-confirmed, issuer-tentative, estimated from reporting history (status `estimated`, with the basis in `explanation`), or reported (with the filing). Dates are issuer-local. Up to 93 days, or ten years with `cik`. `view=compact` drops logos, websites, the quoted disclosure sentence and revision bookkeeping.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "from", "in": "query", "description": "First day, YYYY-MM-DD (default today).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD (default `from`).", "schema": { "type": "string" } }, { "name": "cik", "in": "query", "description": "Numeric CIK (1–10 digits) or platform key (letters then digits, at most 10 characters): that company's dates; widens the window limit to ten years.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Uppercase ISO alpha-2 market codes, comma-separated, up to 80 (e.g. AE,SA). Lowercase codes answer 400.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Only this status.", "schema": { "type": "string", "enum": [ "estimated", "issuer_tentative", "confirmed", "elapsed", "reported", "postponed", "cancelled", "disputed" ] } }, { "name": "search", "in": "query", "description": "Company name or ticker contains; max 100 characters.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1–1000, default 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "view", "in": "query", "description": "`compact` drops display-only fields (logos, websites).", "schema": { "type": "string", "enum": [ "full", "compact" ], "default": "full" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar" ], "callable": true }, { "id": "post-call-recordings-for-calendar-events", "method": "POST", "path": "/api/v1/earnings/calendar/recordings", "title": "Call recordings for calendar events", "description": "Which calendar events have a stored call recording: for each `{ id, cik, dates }` (up to 600 events; `id` at most 120 characters, `cik` 1–12 letters or digits, `dates` 1–3 YYYY-MM-DD days), `recordings[id]` gives the transcript id, date partition, whether video exists and the quarter label. Events without a recording are absent.", "groups": [ "Company Data" ], "tier": "free", "parameters": [], "request_body": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "maxItems": 600, "items": { "type": "object", "required": [ "id", "cik", "dates" ], "properties": { "id": { "type": "string" }, "cik": { "type": "string" }, "dates": { "type": "array", "items": { "type": "string", "format": "date" } } } } } } } } } }, "response_types": [ "application/json" ], "mcp_tools": [], "callable": false }, { "id": "get-earnings-date-detail", "method": "GET", "path": "/api/v1/earnings/calendar/{id}", "title": "Earnings date detail", "description": "One results date: the event, the revisions of its date with the evidence for each (newest first, at most 100), the company's past results dates, and the headline results once reported. The estimator re-saves an unchanged estimate on every run: `revisions=changes` keeps only the revisions that changed the date, status or evidence, each with `repeated` (identical re-saves that followed it) and `lastConfirmedAt` (the last one's time), and adds `revisionsTotal` and `revisionsCollapsed`.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The event id as the calendar returned it.", "schema": { "type": "string" } }, { "name": "revisions", "in": "query", "description": "all (default): every revision. changes: only those that changed the date, status or evidence.", "schema": { "type": "string", "enum": [ "all", "changes" ], "default": "all" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar_event" ], "callable": true }, { "id": "get-live-earnings-calls", "method": "GET", "path": "/api/v1/earnings/live", "title": "Live earnings calls", "description": "The earnings calls being streamed now, largest company first; `calls: []` when none is live.", "groups": [ "Company Data" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar" ], "callable": true }, { "id": "get-economic-calendar", "method": "GET", "path": "/api/v1/economic/calendar", "title": "Economic calendar", "description": "Scheduled statistical releases and central-bank decisions in a window (up to 400 days) from every stored release calendar (US today; each event names its `country`), cancelled dates excluded, each with its importance, status and, once released, the headline series' print (actual, prior, year-ago). `importance` is a floor. Without `limit`/`offset` the whole window, at most 1,500 dates read before `search` and `importance` filter them; `truncated` says the window held more. `status`: scheduled, released (the headline print is held), awaiting (the date has passed, or the agency has published, and the headline print is not in our copy yet; served so for 45 days after the date), or cancelled. `summary.awaiting` counts those and `stale` is true when any is served. The reply echoes the window as `from` / `to` (default today).", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "from", "in": "query", "description": "First day, YYYY-MM-DD (default today).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD (default `from`).", "schema": { "type": "string" } }, { "name": "importance", "in": "query", "description": "Minimum importance.", "schema": { "type": "string", "enum": [ "high", "medium", "low" ] } }, { "name": "search", "in": "query", "description": "Release name, short name, source agency or headline series title/id contains (case-insensitive); max 100 characters.", "schema": { "type": "string" } }, { "name": "release", "in": "query", "description": "One release id.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Page size, 1–500 (500 when only `offset` is given); with `offset`, pages the window (`nextOffset` names the next page). Without both, the whole window.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar" ], "callable": true }, { "id": "get-economic-release-detail", "method": "GET", "path": "/api/v1/economic/calendar/{id}", "title": "Economic release detail", "description": "One release event: its series with their prints and the release's next scheduled dates.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The event id as the calendar returned it.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar_event" ], "callable": true }, { "id": "get-corporate-events-calendar", "method": "GET", "path": "/api/v1/corporate/calendar", "title": "Corporate events calendar", "description": "Dated corporate events from issuer disclosure in a window (up to 93 days): shareholder meetings, leadership changes, dividends (declared, record and pay dates), capital actions and deals, exchange listings. Each row names its filing (accession, sourceUrl).", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "from", "in": "query", "description": "First day, YYYY-MM-DD (default today).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD (default `from`).", "schema": { "type": "string" } }, { "name": "kinds", "in": "query", "description": "Comma-separated: meeting, leadership, dividend, capital, listing, other.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Uppercase ISO alpha-2 market codes, comma-separated, up to 80 (e.g. AE,SA). Lowercase codes answer 400.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Company name, ticker or CIK contains (also matches company-name search aliases); max 100 characters. Event text is not searched.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–500 (500 when only `offset` is given); with `offset`, pages the window (`nextOffset` names the next page). Without both, the whole window.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "view", "in": "query", "description": "`compact` drops display-only fields (logos, websites).", "schema": { "type": "string", "enum": [ "full", "compact" ], "default": "full" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar" ], "callable": true }, { "id": "get-congressional-calendar", "method": "GET", "path": "/api/v1/congressional/calendar", "title": "Congressional calendar", "description": "US House and Senate committee meetings in a window (up to 93 days, Washington days), each chamber's session days, and how far each chamber's published calendar reaches. Cancelled and postponed meetings keep their status. `limit`/`offset` page the meetings; session days are always whole.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "from", "in": "query", "description": "First day, YYYY-MM-DD (default today).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD (default `from`).", "schema": { "type": "string" } }, { "name": "chamber", "in": "query", "description": "One chamber: house or senate (joint meetings are returned only when no chamber is given).", "schema": { "type": "string", "enum": [ "house", "senate" ] } }, { "name": "kinds", "in": "query", "description": "Comma-separated: hearing, markup, business.", "schema": { "type": "string" } }, { "name": "committee", "in": "query", "description": "Committee system code, e.g. ssbk00.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Meeting title or location contains (case-insensitive); max 100 characters.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–500 (500 when only `offset` is given); with `offset`, pages the window (`nextOffset` names the next page). Without both, the whole window.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar" ], "callable": true }, { "id": "get-congressional-meeting", "method": "GET", "path": "/api/v1/congressional/calendar/{id}", "title": "Congressional meeting", "description": "One committee meeting, e.g. house:119515: committees, witnesses, location and the publisher's page.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The event id as the calendar returned it.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar_event" ], "callable": true }, { "id": "get-management-votes", "method": "GET", "path": "/api/v1/companies/{id}/management", "title": "Management & votes", "description": "Officers, directors, leadership changes and shareholder votes.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_management" ], "callable": true }, { "id": "get-ownership-summary", "method": "GET", "path": "/api/v1/companies/{id}/ownership", "title": "Ownership summary", "description": "Insider positions (with the licence attribution when they come from an open-data register, e.g. Taiwan), up to 50 Form 144 notices, the top 50 13F institutional holders, and the shareholder nationality split where the source publishes one (empty for US issuers). Transactions: /ownership/transactions.", "groups": [ "Ownership & Insiders" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_ownership" ], "callable": true }, { "id": "get-insider-transactions", "method": "GET", "path": "/api/v1/companies/{id}/ownership/transactions", "title": "Insider transactions", "description": "Insider transactions (Forms 3/4/5), newest first.", "groups": [ "Ownership & Insiders" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "Transaction kind; any other value is a 400.", "schema": { "type": "string", "enum": [ "All", "Sales", "Purchases", "Awards", "Other" ], "default": "All" } }, { "name": "derivatives", "in": "query", "description": "true to include derivative-security rows.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "page", "in": "query", "description": "1-based, default 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "description": "1–100, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "from", "in": "query", "description": "First transaction date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last transaction date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "owner", "in": "query", "description": "Reporting-owner CIKs, comma-separated.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_ownership" ], "callable": true }, { "id": "get-insider-position-history", "method": "GET", "path": "/api/v1/companies/{id}/ownership/insider-history", "title": "Insider position history", "description": "Every served position snapshot of the company's current insiders, restated on today's share basis, with the splits applied. Not paged: `limit` or `offset` answers 400.", "groups": [ "Ownership & Insiders" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "owner", "in": "query", "description": "Reporting-owner CIKs, comma-separated.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "First snapshot date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last snapshot date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_ownership" ], "callable": true }, { "id": "get-foreign-ownership-history", "method": "GET", "path": "/api/v1/companies/{id}/ownership/nationality-history", "title": "Foreign ownership history", "description": "Stored foreign-ownership snapshots, oldest first.", "groups": [ "Ownership & Insiders" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "First snapshot date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last snapshot date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Page size, 1–5000.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_ownership" ], "callable": true }, { "id": "get-company-signals", "method": "GET", "path": "/api/v1/companies/{id}/signals", "title": "Company signals", "description": "Deterministic signals from filings: insider open-market buys (newest 100), director-election dissent, red-flag 8-Ks, board interlocks, 13F holder rotation for the latest reported quarter (`rotation.period`; counts per change and the 15 largest moves; a manager counts in a quarter once its 13F for that quarter is indexed, so a quarter whose 13Fs are still arriving shows few or none), filing latency, and leadership-change backtest aggregates.", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company" ], "callable": true }, { "id": "get-company-scorecard", "method": "GET", "path": "/api/v1/companies/{id}/scorecard", "title": "Company scorecard", "description": "Guidance-vs-actual scorecard.", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_guidance" ], "callable": true }, { "id": "get-earnings-overview", "method": "GET", "path": "/api/v1/companies/{id}/earnings/overview", "title": "Earnings overview", "description": "Quarterly revenue and EPS (newest 16 quarters by default; see quarters), the market's measured reaction to each call, and highlights from the latest call.", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "quarters", "in": "query", "description": "Quarters of history: 1–200, or `all`. Default 16.", "schema": { "type": "string", "pattern": "^(all|[1-9][0-9]?|1[0-9]{2}|200)$", "minimum": 1, "maximum": 200, "default": 16 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_earnings" ], "callable": true }, { "id": "get-guidance-commitments", "method": "GET", "path": "/api/v1/companies/{id}/earnings/promises", "title": "Guidance commitments", "description": "Every forward-looking statement from the latest earnings call(s), quote first and without a verdict, plus the confirmed commitments resolved at the latest results.", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_guidance" ], "callable": true }, { "id": "get-guidance-scorecard", "method": "GET", "path": "/api/v1/companies/{id}/earnings/scorecard", "title": "Guidance scorecard", "description": "Per-call scorecard of commitments kept vs missed.", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_guidance" ], "callable": true }, { "id": "get-transcript-index", "method": "GET", "path": "/api/v1/companies/{id}/transcripts", "title": "Transcript index", "description": "Earnings-call transcript index.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_transcripts", "get_transcript" ], "callable": true }, { "id": "get-transcript-text", "method": "GET", "path": "/api/v1/companies/{id}/transcripts/{transcriptId}", "title": "Transcript text", "description": "One transcript, as plain text with speaker turns.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "transcriptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "description": "The transcript's date (YYYY-MM-DD) exactly as returned by the transcript index.", "schema": { "type": "string", "format": "date" } } ], "request_body": null, "response_types": [ "text/plain" ], "mcp_tools": [ "get_transcript" ], "callable": true }, { "id": "get-transcript-annotations", "method": "GET", "path": "/api/v1/companies/{id}/transcripts/{transcriptId}/annotations", "title": "Transcript annotations", "description": "Every observation extracted from this transcript, with exact character spans into the transcript text, verification status, narrative assignments and claim-graph edge links. The company in the path is not checked; 404 when the transcript has no extractions.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "transcriptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_transcript" ], "callable": true }, { "id": "get-transcript-search", "method": "GET", "path": "/api/v1/transcripts/search", "title": "Transcript search", "description": "Full-text search over every spoken word in the transcript corpus (websearch syntax: quoted phrases, OR, -exclusion), or with `mentioned` the passages where other companies name that company. Each passage carries the speaker and role, the speaking company, the call and date, a highlighted snippet, and charStart/charEnd — the exact span in the transcript text.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "topicColumns", "in": "query", "description": "JSON array of 1–12 ordered columns: id, label, terms, exclude, match (any/all). Each phrase is literal text; exclusions apply across all alternatives. Definitions must fit a 6,000-character URL-encoded budget.", "schema": { "type": "string" } }, { "name": "column", "in": "query", "description": "Apply a column from topicColumns (or the default set) to source passages.", "schema": { "type": "string" } }, { "name": "q2", "in": "query", "description": "Second websearch expression; combined with q in the same speaker passage.", "schema": { "type": "string" } }, { "name": "termMatch", "in": "query", "description": "Combine q and q2 using all (AND) or any (OR).", "schema": { "type": "string", "enum": [ "all", "any" ], "default": "all" } }, { "name": "topic", "in": "query", "description": "Inspectable lexical research topic.", "schema": { "type": "string", "enum": [ "demand", "pricing", "margins", "investment", "ai", "credit", "funding", "regulation", "returns", "outlook" ] } }, { "name": "browse", "in": "query", "description": "1 = browse source turns without a keyword predicate.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "Issuer region from the country catalog.", "schema": { "type": "string" } }, { "name": "subregion", "in": "query", "description": "Issuer subregion from the country catalog.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Exact city in the company's currently stored business address; missing addresses remain unknown.", "schema": { "type": "string" } }, { "name": "locationMode", "in": "query", "description": "Inside or outside the intersection of selected country/region/subregion/city.", "schema": { "type": "string", "enum": [ "inside", "outside" ], "default": "inside" } }, { "name": "includeUnknownLocation", "in": "query", "description": "1 = include unknown geography in outside searches; excluded by default.", "schema": { "type": "string" } }, { "name": "theme", "in": "query", "description": "Explicit lexical theme; AND with q in the same passage.", "schema": { "type": "string", "enum": [ "purchase-delays", "pricing-pressure", "pricing-power", "ai-investment", "inventory", "capacity", "tariffs", "guidance" ] } }, { "name": "speaker", "in": "query", "description": "Speaker name contains; max 120 characters.", "schema": { "type": "string" } }, { "name": "includeContext", "in": "query", "description": "1 = include bounded surrounding turns or indexed Q&A exchange; truncation flagged.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Websearch query; combine with mentioned or theme to narrow the same passage.", "schema": { "type": "string" } }, { "name": "mentioned", "in": "query", "description": "Company talked about — ticker, CIK or platform key (mentions mode).", "schema": { "type": "string" } }, { "name": "company", "in": "query", "description": "Only calls held by this company.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Source issuer country from transcript metadata: uppercase ISO alpha-2 code, or unknown for missing geography.", "schema": { "type": "string" } }, { "name": "companies", "in": "query", "description": "Comma-separated company basket, at most 20 identifiers; intersects company if supplied.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Speaker role.", "schema": { "type": "string", "enum": [ "executive", "analyst", "operator" ] } }, { "name": "section", "in": "query", "description": "Part of the call.", "schema": { "type": "string", "enum": [ "prepared", "qa" ] } }, { "name": "from", "in": "query", "description": "Calls on or after, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Calls on or before, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "description": "newest (default) or relevance; relevance applies only with q, q2, theme, topic or column, otherwise newest is used.", "schema": { "type": "string", "enum": [ "newest", "relevance" ], "default": "newest" } }, { "name": "limit", "in": "query", "description": "1–50, default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "description": "nextCursor from the previous page.", "schema": { "type": "string" } }, { "name": "includeSelf", "in": "query", "description": "1 = include the mentioned company's own calls.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "search_transcripts" ], "callable": true }, { "id": "get-transcript-search-summary", "method": "GET", "path": "/api/v1/transcripts/search/summary", "title": "Transcript search summary", "description": "The same search, summarized: matches per calendar quarter, the companies doing the talking, and companyQuarters counts of matching calls and passages for the leading companies. countries carries issuer country/region counts across all matches. Sampled summaries omit companyQuarters and countries detail.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "topicColumns", "in": "query", "description": "JSON array of 1–12 ordered columns: id, label, terms, exclude, match (any/all). Each phrase is literal text; exclusions apply across all alternatives. Definitions must fit a 6,000-character URL-encoded budget.", "schema": { "type": "string" } }, { "name": "column", "in": "query", "description": "Apply a column from topicColumns (or the default set) to source passages.", "schema": { "type": "string" } }, { "name": "q2", "in": "query", "description": "Second websearch expression; combined with q in the same speaker passage.", "schema": { "type": "string" } }, { "name": "termMatch", "in": "query", "description": "Combine q and q2 using all (AND) or any (OR).", "schema": { "type": "string", "enum": [ "all", "any" ], "default": "all" } }, { "name": "topic", "in": "query", "description": "Inspectable lexical research topic.", "schema": { "type": "string", "enum": [ "demand", "pricing", "margins", "investment", "ai", "credit", "funding", "regulation", "returns", "outlook" ] } }, { "name": "browse", "in": "query", "description": "1 = browse source turns without a keyword predicate.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "Issuer region from the country catalog.", "schema": { "type": "string" } }, { "name": "subregion", "in": "query", "description": "Issuer subregion from the country catalog.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Exact city in the company's currently stored business address; missing addresses remain unknown.", "schema": { "type": "string" } }, { "name": "locationMode", "in": "query", "description": "Inside or outside the intersection of selected country/region/subregion/city.", "schema": { "type": "string", "enum": [ "inside", "outside" ], "default": "inside" } }, { "name": "includeUnknownLocation", "in": "query", "description": "1 = include unknown geography in outside searches; excluded by default.", "schema": { "type": "string" } }, { "name": "theme", "in": "query", "description": "Explicit lexical theme; AND with q in the same passage.", "schema": { "type": "string", "enum": [ "purchase-delays", "pricing-pressure", "pricing-power", "ai-investment", "inventory", "capacity", "tariffs", "guidance" ] } }, { "name": "speaker", "in": "query", "description": "Speaker name contains; max 120 characters.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Websearch query; combine with mentioned or theme to narrow the same passage.", "schema": { "type": "string" } }, { "name": "mentioned", "in": "query", "description": "Company talked about (mentions mode).", "schema": { "type": "string" } }, { "name": "company", "in": "query", "description": "Only calls held by this company.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Source issuer country from transcript metadata: uppercase ISO alpha-2 code, or unknown for missing geography.", "schema": { "type": "string" } }, { "name": "companies", "in": "query", "description": "Comma-separated company basket, at most 20 identifiers; intersects company if supplied.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Speaker role.", "schema": { "type": "string", "enum": [ "executive", "analyst", "operator" ] } }, { "name": "section", "in": "query", "description": "Part of the call.", "schema": { "type": "string", "enum": [ "prepared", "qa" ] } }, { "name": "from", "in": "query", "description": "Calls on or after, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Calls on or before, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "includeSelf", "in": "query", "description": "1 = include the mentioned company's own calls.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "search_transcripts" ], "callable": true }, { "id": "get-transcript-topic-analysis", "method": "GET", "path": "/api/v1/transcripts/search/topics", "title": "Transcript topic analysis", "description": "Lexical company/topic matrix, calendar topic evolution, analyst Q&A turn counts and comparison with an immediately preceding equal-day window. Defaults to the latest twelve months when from is omitted; without a company scope (company, companies or mentioned) a window is at most 92 days and defaults to the 92 days ending `to`, and a wider one is a 400. Topic caps are explicit; geographic and text filters match source turns.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "topicColumns", "in": "query", "description": "JSON array of 1–12 ordered columns: id, label, terms, exclude, match (any/all). Each phrase is literal text; exclusions apply across all alternatives. Definitions must fit a 6,000-character URL-encoded budget.", "schema": { "type": "string" } }, { "name": "column", "in": "query", "description": "Apply a column from topicColumns (or the default set) to source passages.", "schema": { "type": "string" } }, { "name": "q2", "in": "query", "description": "Second websearch expression; combined with q in the same speaker passage.", "schema": { "type": "string" } }, { "name": "termMatch", "in": "query", "description": "Combine q and q2 using all (AND) or any (OR).", "schema": { "type": "string", "enum": [ "all", "any" ], "default": "all" } }, { "name": "topic", "in": "query", "description": "Inspectable lexical research topic.", "schema": { "type": "string", "enum": [ "demand", "pricing", "margins", "investment", "ai", "credit", "funding", "regulation", "returns", "outlook" ] } }, { "name": "browse", "in": "query", "description": "1 = browse source turns without a keyword predicate.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "Issuer region from the country catalog.", "schema": { "type": "string" } }, { "name": "subregion", "in": "query", "description": "Issuer subregion from the country catalog.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Exact city in the company's currently stored business address; missing addresses remain unknown.", "schema": { "type": "string" } }, { "name": "locationMode", "in": "query", "description": "Inside or outside the intersection of selected country/region/subregion/city.", "schema": { "type": "string", "enum": [ "inside", "outside" ], "default": "inside" } }, { "name": "includeUnknownLocation", "in": "query", "description": "1 = include unknown geography in outside searches; excluded by default.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Primary websearch expression.", "schema": { "type": "string" } }, { "name": "mentioned", "in": "query", "description": "Company being named.", "schema": { "type": "string" } }, { "name": "theme", "in": "query", "description": "Explicit lexical theme: purchase-delays, pricing-pressure, pricing-power, ai-investment, inventory, capacity, tariffs, guidance.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Issuer ISO alpha-2 country or unknown.", "schema": { "type": "string" } }, { "name": "company", "in": "query", "description": "Speaking company.", "schema": { "type": "string" } }, { "name": "companies", "in": "query", "description": "Company basket, up to 20 identifiers.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Speaker role.", "schema": { "type": "string" } }, { "name": "section", "in": "query", "description": "prepared or qa.", "schema": { "type": "string" } }, { "name": "speaker", "in": "query", "description": "Speaker name contains.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Current comparison window start, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Current comparison window end, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "includeSelf", "in": "query", "description": "1 includes subject's own calls.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "analyze_transcript_topics" ], "callable": true }, { "id": "get-transcript-geography-options", "method": "GET", "path": "/api/v1/transcripts/search/facets", "title": "Transcript geography options", "description": "Without parameters: every country as { code, name } (no region or subregion fields). With country=XX: the business-address cities of companies holding a transcript there, with company counts.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "country", "in": "query", "description": "Two-letter country code: adds that country's cities with their company counts.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "search_transcripts" ], "callable": true }, { "id": "get-mentioned-by", "method": "GET", "path": "/api/v1/companies/{id}/mentioned-by", "title": "Mentioned by", "description": "Where this company is talked about on OTHER companies' earnings calls and events — newest first, speaker named, exact span in the source transcript. Its own calls are excluded unless includeSelf=1.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "topicColumns", "in": "query", "description": "JSON array of 1–12 ordered columns: id, label, terms, exclude, match (any/all). Each phrase is literal text; exclusions apply across all alternatives. Definitions must fit a 6,000-character URL-encoded budget.", "schema": { "type": "string" } }, { "name": "column", "in": "query", "description": "Apply a column from topicColumns (or the default set) to source passages.", "schema": { "type": "string" } }, { "name": "q2", "in": "query", "description": "Second websearch expression; combined with q in the same speaker passage.", "schema": { "type": "string" } }, { "name": "termMatch", "in": "query", "description": "Combine q and q2 using all (AND) or any (OR).", "schema": { "type": "string", "enum": [ "all", "any" ], "default": "all" } }, { "name": "topic", "in": "query", "description": "Inspectable lexical research topic.", "schema": { "type": "string", "enum": [ "demand", "pricing", "margins", "investment", "ai", "credit", "funding", "regulation", "returns", "outlook" ] } }, { "name": "browse", "in": "query", "description": "1 = browse source turns without a keyword predicate.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "Issuer region from the country catalog.", "schema": { "type": "string" } }, { "name": "subregion", "in": "query", "description": "Issuer subregion from the country catalog.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Exact city in the company's currently stored business address; missing addresses remain unknown.", "schema": { "type": "string" } }, { "name": "locationMode", "in": "query", "description": "Inside or outside the intersection of selected country/region/subregion/city.", "schema": { "type": "string", "enum": [ "inside", "outside" ], "default": "inside" } }, { "name": "includeUnknownLocation", "in": "query", "description": "1 = include unknown geography in outside searches; excluded by default.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Optional keyword query within a company mention.", "schema": { "type": "string" } }, { "name": "theme", "in": "query", "description": "Explicit lexical theme; AND with q in the same passage.", "schema": { "type": "string", "enum": [ "purchase-delays", "pricing-pressure", "pricing-power", "ai-investment", "inventory", "capacity", "tariffs", "guidance" ] } }, { "name": "speaker", "in": "query", "description": "Speaker name contains; max 120 characters.", "schema": { "type": "string" } }, { "name": "includeContext", "in": "query", "description": "1 = include bounded surrounding turns or indexed Q&A exchange; truncation flagged.", "schema": { "type": "string" } }, { "name": "company", "in": "query", "description": "Only calls held by this company.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Source issuer country from transcript metadata: uppercase ISO alpha-2 code, or unknown for missing geography.", "schema": { "type": "string" } }, { "name": "companies", "in": "query", "description": "Comma-separated company basket, at most 20 identifiers; intersects company if supplied.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Speaker role.", "schema": { "type": "string", "enum": [ "executive", "analyst", "operator" ] } }, { "name": "section", "in": "query", "description": "Part of the call.", "schema": { "type": "string", "enum": [ "prepared", "qa" ] } }, { "name": "from", "in": "query", "description": "Calls on or after, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Calls on or before, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "description": "newest (default) or relevance; relevance applies only with q, q2, theme, topic or column, otherwise newest is used.", "schema": { "type": "string", "enum": [ "newest", "relevance" ], "default": "newest" } }, { "name": "limit", "in": "query", "description": "1–50, default 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "description": "nextCursor from the previous page.", "schema": { "type": "string" } }, { "name": "includeSelf", "in": "query", "description": "1 = include the company's own calls.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_mentioned_by" ], "callable": true }, { "id": "get-mentioned-by-summary", "method": "GET", "path": "/api/v1/companies/{id}/mentioned-by/summary", "title": "Mentioned by summary", "description": "Mentions of this company on other companies' calls per calendar quarter, plus the companies doing the talking.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "topicColumns", "in": "query", "description": "JSON array of 1–12 ordered columns: id, label, terms, exclude, match (any/all). Each phrase is literal text; exclusions apply across all alternatives. Definitions must fit a 6,000-character URL-encoded budget.", "schema": { "type": "string" } }, { "name": "column", "in": "query", "description": "Apply a column from topicColumns (or the default set) to source passages.", "schema": { "type": "string" } }, { "name": "q2", "in": "query", "description": "Second websearch expression; combined with q in the same speaker passage.", "schema": { "type": "string" } }, { "name": "termMatch", "in": "query", "description": "Combine q and q2 using all (AND) or any (OR).", "schema": { "type": "string", "enum": [ "all", "any" ], "default": "all" } }, { "name": "topic", "in": "query", "description": "Inspectable lexical research topic.", "schema": { "type": "string", "enum": [ "demand", "pricing", "margins", "investment", "ai", "credit", "funding", "regulation", "returns", "outlook" ] } }, { "name": "browse", "in": "query", "description": "1 = browse source turns without a keyword predicate.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "Issuer region from the country catalog.", "schema": { "type": "string" } }, { "name": "subregion", "in": "query", "description": "Issuer subregion from the country catalog.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Exact city in the company's currently stored business address; missing addresses remain unknown.", "schema": { "type": "string" } }, { "name": "locationMode", "in": "query", "description": "Inside or outside the intersection of selected country/region/subregion/city.", "schema": { "type": "string", "enum": [ "inside", "outside" ], "default": "inside" } }, { "name": "includeUnknownLocation", "in": "query", "description": "1 = include unknown geography in outside searches; excluded by default.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Optional keyword query within a company mention.", "schema": { "type": "string" } }, { "name": "theme", "in": "query", "description": "Explicit lexical theme; AND with q in the same passage.", "schema": { "type": "string", "enum": [ "purchase-delays", "pricing-pressure", "pricing-power", "ai-investment", "inventory", "capacity", "tariffs", "guidance" ] } }, { "name": "speaker", "in": "query", "description": "Speaker name contains; max 120 characters.", "schema": { "type": "string" } }, { "name": "company", "in": "query", "description": "Only calls held by this company.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Source issuer country from transcript metadata: uppercase ISO alpha-2 code, or unknown for missing geography.", "schema": { "type": "string" } }, { "name": "companies", "in": "query", "description": "Comma-separated company basket, at most 20 identifiers; intersects company if supplied.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Speaker role.", "schema": { "type": "string", "enum": [ "executive", "analyst", "operator" ] } }, { "name": "section", "in": "query", "description": "Part of the call.", "schema": { "type": "string", "enum": [ "prepared", "qa" ] } }, { "name": "from", "in": "query", "description": "Calls on or after, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Calls on or before, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "includeSelf", "in": "query", "description": "1 = include the company's own calls.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_mentioned_by" ], "callable": true }, { "id": "get-observations", "method": "GET", "path": "/api/v1/companies/{id}/observations", "title": "Observations", "description": "Span-verified 8-K event observations, newest event first (event date, else filing date). Calls are not a source. Paged: `limit` (1–500, default 50, for every caller) and `offset`; the body carries `total`, `limit`, `offset`, `hasMore` and `nextOffset`. Rows are read from the newest 500, so from/to and offset page only within those 500.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "family", "in": "query", "description": "Event family (same list as /events/wire); an unknown one is a 400.", "schema": { "type": "string" } }, { "name": "includeReview", "in": "query", "description": "Include rows still under review (1).", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "First filing date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last filing date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–500, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip (the previous `nextOffset`), default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_events", "get_event_facts" ], "callable": true }, { "id": "get-ir-presentations", "method": "GET", "path": "/api/v1/companies/{id}/presentations", "title": "IR presentations", "description": "Investor-presentation decks, newest first: 8-K exhibits stored as slide images (format slides) and exchange or IR-site results decks (format pdf, opened through the filings document route). Undated decks are placed on their fiscal period end; undated ones without a period come last.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "First filing date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last filing date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Page size, 1–200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "dedupe", "in": "query", "description": "1 (the default) collapses the same deck published more than once (an 8-K exhibit and the IR-site copy) into one row and says how many were collapsed in `duplicatesCollapsed`; 0 lists every copy.", "schema": { "type": "string", "enum": [ "1", "0" ], "default": "1" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_presentations" ], "callable": true }, { "id": "get-presentation-guidance", "method": "GET", "path": "/api/v1/companies/{id}/presentation-guidance", "title": "Presentation guidance", "description": "Guidance the company printed in its investor presentations, every disclosure kept (the same target said in several decks is several rows), each with its deck (`doc_ref`) and page. Newest deck first by default; paged (`total`, `limit`, `offset`, `hasMore`, `nextOffset`); `keys` lists every guidance key the company has with its label and row count.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "description": "Guidance keys, comma-separated.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Guidance kinds, comma-separated.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "First published date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last published date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Rows per page, 1–500, default 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "description": "Rows to skip: the previous reply's `nextOffset`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "sort", "in": "query", "description": "`newest` puts the latest deck first (the default; undated last), `target` orders by the period targeted (latest first), `key` groups by metric (the Guidance table's order).", "schema": { "type": "string", "enum": [ "newest", "target", "key" ], "default": "newest" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_guidance", "get_presentations" ], "callable": true }, { "id": "get-market-events", "method": "GET", "path": "/api/v1/companies/{id}/market-events", "title": "Market events", "description": "Dated events to overlay on the company's charts: global, regional, country, exchange and company events, and Ramadan for Muslim-majority markets.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "max_tier", "in": "query", "description": "Least important tier to include, 1–3, default 3; any other value is read as 3.", "schema": { "type": "integer", "minimum": 1, "maximum": 3, "default": 3 } }, { "name": "economy", "in": "query", "description": "ISO alpha-2 economy for economic events (recessions); default the home country, else US.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Categories, comma-separated, e.g. war_conflict,financial_crisis.", "schema": { "type": "string" } }, { "name": "exclude_category", "in": "query", "description": "Categories to drop, e.g. calendar (Ramadan).", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "First day (events overlapping the window), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Page size, 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "order", "in": "query", "description": "Date order: `asc` oldest first (the default), `desc` newest first.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_market_events" ], "callable": true }, { "id": "get-presentation-page-image", "method": "GET", "path": "/api/v1/companies/{id}/presentations/{presentationId}/pages/{page}", "title": "Presentation page image", "description": "One rendered page image of an IR deck.", "groups": [ "Transcripts & Calls" ], "tier": "public", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "presentationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "path", "required": true, "schema": { "type": "integer" } } ], "request_body": null, "response_types": [ "image/*" ], "mcp_tools": [], "callable": true }, { "id": "get-compute-exposure", "method": "GET", "path": "/api/v1/companies/{id}/compute", "title": "Compute exposure", "description": "Compute / GPU exposure for hyperscalers and neoclouds. {id} must be a ticker (letters, dots, dashes; a CIK is a 400); 404 when the company is not in the compute set.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-latest-filings", "method": "GET", "path": "/api/v1/filings", "title": "Latest filings", "description": "Newest documents across every source: completed SEC EDGAR filings and the exchange, regulator and IR documents we store (DFM, ADX, Tadawul, QSE, DART, EDINET, …), newest first.", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "limit", "in": "query", "description": "1–100, default 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "offset", "in": "query", "description": "Default 0; the response carries hasMore and nextOffset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "family", "in": "query", "description": "Only filings of one family: annual (10-K, 20-F, exchange annual reports), interim (10-Q, exchange interims), current (8-K, 6-K, exchange disclosures), press, insider (Forms 3/4/5), holdings (13F, 13D/G), meetings (proxies, AGMs) or calls (exchange calls and decks).", "schema": { "type": "string", "enum": [ "annual", "interim", "current", "press", "insider", "holdings", "meetings", "calls" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_filings" ], "callable": true }, { "id": "get-filing-by-accession", "method": "GET", "path": "/api/v1/filings/{accession}", "title": "Filing by accession", "description": "The primary document of a completed SEC filing, as sanitized HTML (text/html), by SEC accession number (0000000000-00-000000, dashes optional). Exchange documents (doc_ref ids from /filings) are not served here.", "groups": [ "SEC Filings" ], "tier": "free", "parameters": [ { "name": "accession", "in": "path", "required": true, "description": "SEC accession number, e.g. 0001045810-25-000023.", "schema": { "type": "string" } }, { "name": "issuer", "in": "query", "description": "For a 13F filing only: keep the information-table rows whose issuer name contains this text (≤200 characters).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "text/html" ], "mcp_tools": [ "get_document_text" ], "callable": true }, { "id": "get-latest-events", "method": "GET", "path": "/api/v1/events/latest", "title": "Latest events", "description": "Newest span-verified 8-K event headlines across published companies, newest filing first.", "groups": [ "8-K Events" ], "tier": "free", "parameters": [ { "name": "family", "in": "query", "description": "One event family (same list as /events/wire); an unknown one is a 400.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1–100, default 30.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-event-wire", "method": "GET", "path": "/api/v1/events/wire", "title": "Event wire", "description": "Searchable headline wire of 8-K items and exchange disclosures across published companies: newest filing first (`sort=oldest` reverses), paged. The body carries `headlines`, `total`, `limit`, `offset`, `hasMore`, `nextOffset` (null on the last page), `sort` and `asOf` (when the feed it was cut from was read; it is cached for two minutes). Every value is checked: a bad one is a 400 naming it.", "groups": [ "8-K Events" ], "tier": "free", "parameters": [ { "name": "q", "in": "query", "description": "One phrase, case-insensitive, matched as a substring of the headline, the ticker or the company name; not the filing text and no search syntax. At most 200 characters.", "schema": { "type": "string" } }, { "name": "family", "in": "query", "description": "Event families, comma-separated or repeated: dividend, stock_split, guidance, earnings, mna, debt_financing, equity_financing, buyback, restatement_non_reliance, cyber_incident, restructuring, impairment, leadership, governance_vote, agreement, legal_regulatory, listing_compliance, other. An unknown one is a 400.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "dividend", "stock_split", "guidance", "earnings", "mna", "debt_financing", "equity_financing", "buyback", "restatement_non_reliance", "cyber_incident", "restructuring", "impairment", "leadership", "governance_vote", "agreement", "legal_regulatory", "listing_compliance", "other" ] } } }, { "name": "from", "in": "query", "description": "First filing date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last filing date, YYYY-MM-DD; not before `from`.", "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "description": "Filing-date order.", "schema": { "type": "string", "enum": [ "newest", "oldest" ], "default": "newest" } }, { "name": "limit", "in": "query", "description": "Page size, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip: the previous `nextOffset`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "counts", "in": "query", "description": "1 adds `familyCounts`: matches per family for the same `q` and dates, ignoring `family`.", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_events" ], "callable": true }, { "id": "get-news-feed", "method": "GET", "path": "/api/v1/news/feed", "title": "News feed", "description": "The intraday news tape: SEC filings as they are accepted, issuer press releases, exchange and regulator notices, central-bank releases and licensed wires, stamped with the source time and the moment Astreus first saw them. Cursor-paged on id: poll forward with after=latestId (+changedSince=serverTime to pick up rewritten headlines), page back with before=nextCursor. Every row carries its source attribution and display policy; snippet/body are withheld where the license does not allow them. An unknown topic or source code, a malformed cursor or a limit above 200 is a 400 naming the parameter; an unknown `cik` is a 404.", "groups": [ "News" ], "tier": "free", "parameters": [ { "name": "after", "in": "query", "description": "Poll: return items with id greater than this (newest first). Pass the previous response's latestId.", "schema": { "type": "integer", "format": "int64" } }, { "name": "before", "in": "query", "description": "Load older: items published before item on the tape (by publication time, then id). Pass the previous response's nextCursor.", "schema": { "type": "integer", "format": "int64" } }, { "name": "changedSince", "in": "query", "description": "ISO 8601; with `after`, also re-send items whose updatedAt is later (headline rewrites, re-tagging). Pass the previous response's serverTime.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Items per page, 1–200, default 100; above 200 is a 400 (page with before=nextCursor).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "tickers", "in": "query", "description": "Comma-separated tickers; items tagged with any of them.", "schema": { "type": "string" } }, { "name": "cik", "in": "query", "description": "Numeric CIK or platform key; items whose primary company or a tagged company entity is this issuer.", "schema": { "type": "string" } }, { "name": "topics", "in": "query", "description": "Comma-separated topic codes (see /news/topics); any of them.", "schema": { "type": "string" } }, { "name": "sources", "in": "query", "description": "Comma-separated source codes (see /news/sources); any of them.", "schema": { "type": "string" } }, { "name": "excludeSources", "in": "query", "description": "Comma-separated source codes to hide (the UI's Markets view hides agency releases, social posts and GDELT links).", "schema": { "type": "string" } }, { "name": "excludeForms", "in": "query", "description": "Comma-separated filing form types to hide (e.g. 4,144,SC 13G); rows without a form are kept.", "schema": { "type": "string" } }, { "name": "flash", "in": "query", "description": "1 to return flash (high-priority) items only; 0 (default) for all.", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } }, { "name": "minImportance", "in": "query", "description": "Minimum importance score 0–100.", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "q", "in": "query", "description": "Full-text query over headline and snippet (websearch syntax: quoted phrases, OR, -exclusion).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_news" ], "callable": true }, { "id": "get-news-story", "method": "GET", "path": "/api/v1/news/items/{id}", "title": "News story", "description": "One story: the item, its entity tags (companies, people, indicators…), the rest of its storyline (same cluster, newest first, up to 10), metadata, and the full text for full_text-licensed sources only (null otherwise).", "groups": [ "News" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "News item id.", "schema": { "type": "integer", "format": "int64" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_news" ], "callable": true }, { "id": "get-search-news", "method": "GET", "path": "/api/v1/news/search", "title": "Search news", "description": "Full-text search over headline and snippet of the served tape, newest first. Accepts the feed's narrowing filters. Paged: `nextCursor` (null when exhausted) is the `before` of the next page. An unknown topic or source code or a limit above 100 is a 400; an unknown `cik` is a 404.", "groups": [ "News" ], "tier": "free", "parameters": [ { "name": "q", "in": "query", "description": "Required. Search text (websearch syntax), at most 200 characters (longer is cut).", "schema": { "type": "string" }, "required": true }, { "name": "limit", "in": "query", "description": "Items per page, 1–100, default 50; above 100 is a 400.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "tickers", "in": "query", "description": "Comma-separated tickers; items tagged with any of them.", "schema": { "type": "string" } }, { "name": "cik", "in": "query", "description": "Numeric CIK or platform key; items whose primary company or a tagged company entity is this issuer.", "schema": { "type": "string" } }, { "name": "topics", "in": "query", "description": "Comma-separated topic codes (see /news/topics); any of them.", "schema": { "type": "string" } }, { "name": "sources", "in": "query", "description": "Comma-separated source codes (see /news/sources); any of them.", "schema": { "type": "string" } }, { "name": "excludeSources", "in": "query", "description": "Comma-separated source codes to hide (the UI's Markets view hides agency releases, social posts and GDELT links).", "schema": { "type": "string" } }, { "name": "excludeForms", "in": "query", "description": "Comma-separated filing form types to hide (e.g. 4,144,SC 13G); rows without a form are kept.", "schema": { "type": "string" } }, { "name": "flash", "in": "query", "description": "1 to return flash (high-priority) items only; 0 (default) for all.", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } }, { "name": "minImportance", "in": "query", "description": "Minimum importance score 0–100.", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "before", "in": "query", "description": "Load older: items published before item on the tape (by publication time, then id). Pass the previous response's nextCursor.", "schema": { "type": "integer", "format": "int64" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_news" ], "callable": true }, { "id": "get-news-topics", "method": "GET", "path": "/api/v1/news/topics", "title": "News topics", "description": "Topic taxonomy (corporate event families, macro, policy, market, sector, region) with a rolling 24-hour item count per topic.", "groups": [ "News" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_news" ], "callable": true }, { "id": "get-news-sources", "method": "GET", "path": "/api/v1/news/sources", "title": "News sources", "description": "Enabled news sources with license class, display policy and the attribution line to render, plus a rolling 24-hour item count.", "groups": [ "News" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_news" ], "callable": true }, { "id": "get-top-news", "method": "GET", "path": "/api/v1/news/top", "title": "Top news", "description": "Most important items in the window, one per storyline (each cluster collapsed to its strongest item), ranked by importance then recency.", "groups": [ "News" ], "tier": "free", "parameters": [ { "name": "window", "in": "query", "description": "Lookback window.", "schema": { "type": "string", "enum": [ "6h", "24h", "7d" ], "default": "24h" } }, { "name": "limit", "in": "query", "description": "1–100, default 30.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_news" ], "callable": true }, { "id": "get-news-stream-sse", "method": "GET", "path": "/api/v1/news/stream", "title": "News stream (SSE)", "description": "Server-Sent Events push of the tape with the feed's filters. Emits `event: items` with a NewsFeedResponse body whenever new or rewritten rows appear (polled every 2 s), a `: ping` comment every 15 s, and closes after ~280 s — reconnect with after=. Without `after` the first event is the current page. `limit` caps each event's rows. A bad filter value is a 400 naming it, before the stream opens.", "groups": [ "News" ], "tier": "free", "parameters": [ { "name": "after", "in": "query", "description": "Resume cursor: only items with id greater than this.", "schema": { "type": "integer", "format": "int64" } }, { "name": "changedSince", "in": "query", "description": "ISO 8601; with `after`, also re-send items whose updatedAt is later (headline rewrites, re-tagging). Pass the previous response's serverTime.", "schema": { "type": "string", "format": "date-time" } }, { "name": "tickers", "in": "query", "description": "Comma-separated tickers; items tagged with any of them.", "schema": { "type": "string" } }, { "name": "cik", "in": "query", "description": "Numeric CIK or platform key; items whose primary company or a tagged company entity is this issuer.", "schema": { "type": "string" } }, { "name": "topics", "in": "query", "description": "Comma-separated topic codes (see /news/topics); any of them.", "schema": { "type": "string" } }, { "name": "sources", "in": "query", "description": "Comma-separated source codes (see /news/sources); any of them.", "schema": { "type": "string" } }, { "name": "excludeSources", "in": "query", "description": "Comma-separated source codes to hide (the UI's Markets view hides agency releases, social posts and GDELT links).", "schema": { "type": "string" } }, { "name": "excludeForms", "in": "query", "description": "Comma-separated filing form types to hide (e.g. 4,144,SC 13G); rows without a form are kept.", "schema": { "type": "string" } }, { "name": "flash", "in": "query", "description": "1 to return flash (high-priority) items only; 0 (default) for all.", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } }, { "name": "minImportance", "in": "query", "description": "Minimum importance score 0–100.", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "q", "in": "query", "description": "Full-text query over headline and snippet (websearch syntax: quoted phrases, OR, -exclusion).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per event, 1–50, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } } ], "request_body": null, "response_types": [ "text/event-stream" ], "mcp_tools": [], "callable": true }, { "id": "get-company-news", "method": "GET", "path": "/api/v1/companies/{id}/news", "title": "Company news", "description": "The company's tape: items whose primary company or a tagged company entity is this issuer or any predecessor in its corporate lineage. Same cursor semantics as /news/feed; `cik` echoes the resolved identifier.", "groups": [ "News" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional) or platform key (e.g. XDFM000002).", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Poll: return items with id greater than this (newest first). Pass the previous response's latestId.", "schema": { "type": "integer", "format": "int64" } }, { "name": "before", "in": "query", "description": "Load older: items published before item on the tape (by publication time, then id). Pass the previous response's nextCursor.", "schema": { "type": "integer", "format": "int64" } }, { "name": "changedSince", "in": "query", "description": "ISO 8601; with `after`, also re-send items whose updatedAt is later (headline rewrites, re-tagging). Pass the previous response's serverTime.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "1–200, default 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "tickers", "in": "query", "description": "Comma-separated tickers; items tagged with any of them.", "schema": { "type": "string" } }, { "name": "topics", "in": "query", "description": "Comma-separated topic codes (see /news/topics); any of them.", "schema": { "type": "string" } }, { "name": "sources", "in": "query", "description": "Comma-separated source codes (see /news/sources); any of them.", "schema": { "type": "string" } }, { "name": "excludeSources", "in": "query", "description": "Comma-separated source codes to hide (the UI's Markets view hides agency releases, social posts and GDELT links).", "schema": { "type": "string" } }, { "name": "excludeForms", "in": "query", "description": "Comma-separated filing form types to hide (e.g. 4,144,SC 13G); rows without a form are kept.", "schema": { "type": "string" } }, { "name": "flash", "in": "query", "description": "1 to return flash (high-priority) items only; 0 (default) for all.", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } }, { "name": "minImportance", "in": "query", "description": "Minimum importance score 0–100.", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "q", "in": "query", "description": "Full-text query over headline and snippet (websearch syntax: quoted phrases, OR, -exclusion).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_news" ], "callable": true }, { "id": "get-list-countries", "method": "GET", "path": "/api/v1/countries", "title": "List countries", "description": "Countries with macro coverage and their headline figures, one page at a time: { countries, sort, order, total, limit, offset, hasMore, nextOffset, page }. Growth is two figures: `real_gdp_growth` (% year on year of real GDP, null where no real series is held) and `nominal_gdp_growth` (% change in nominal GDP on the same period a year earlier: not real growth); `gdp_growth` is a deprecated copy of `nominal_gdp_growth`. `periods` gives each figure's period. Each row's cube-backed values carry `sources` = { gdp, population, inflation, debt, real_gdp_growth }, each { name, fullName, url, note } — the publisher of the series the value was read from; a value without a recorded source is absent from it. A null figure is not held, never zero.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "q", "in": "query", "description": "Words in the name or ISO code.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "Region or sub-region, e.g. Asia, Western Asia.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Rank by this figure, largest first (`name`: A–Z). Default real_gdp_growth. `gdp_growth` is deprecated: it is nominal_gdp_growth.", "schema": { "type": "string", "enum": [ "real_gdp_growth", "nominal_gdp_growth", "gdp_usd_bn", "population", "inflation", "debt_to_gdp", "name", "gdp_growth" ], "default": "real_gdp_growth" } }, { "name": "order", "in": "query", "description": "Default desc (asc for name), nulls last either way.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit", "in": "query", "description": "Page size, 1–250, default 50 once any filter or paging parameter is given; without any, every country is served. A limit above 250 is a 400.", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0: the previous page's `nextOffset`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_countries" ], "callable": true }, { "id": "get-gdp-sparklines", "method": "GET", "path": "/api/v1/countries/gdp-sparklines", "title": "GDP sparklines", "description": "Annual nominal GDP for a set of countries, for mini bar charts: { sparklines: { : { gdp: [number] (billions of US dollars, oldest first), years: [year of each point], growth: [NOMINAL % change on the year before; null when that year is missing], currency } }, unit: \"Billions of US dollars\", growthBasis: \"nominal\", missing: [codes with no annual GDP held] }. Up to six years; forecasts excluded.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "codes", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 codes, comma-separated, up to 500, e.g. US,GB,JP.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-country-dashboard", "method": "GET", "path": "/api/v1/countries/{iso}", "title": "Country dashboard", "description": "Country macro dashboard. By default (`view=profile`, 5–50 KB) the profile — headline figures with their periods, curves, leaders, facts — with `seriesCount`, `branches` (the country page's tabs and sub-tabs the country fills) and `views` (where the rest is read). `view=full` adds every curated indicator as a card in `macroSeries[]` (900–1,700 cards, about 1–1.8 MB): label, units, `latest` (null when the series holds no print yet), `yoyChange` (year on year: the latest print against the same period a year earlier; a % change for levels and indexes, a change in points for rates and percents — `yoyChangeUnit` says which; null when no print a year back is held), `yearAgo` (that print), `priorChange` (latest minus the print before it, in the series' own unit) and a short sparkline (the newest 12 current-vintage observations). One card per key. The full, uncapped current-vintage history of any series is GET /api/v1/countries/{iso}/series?key=. Each card carries `source` = { name, fullName, url, note } — its publisher and where it was retrieved.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`profile` (default): the payload without `macroSeries` (plus `seriesCount`, `branches`: the country page's tabs and sub-tabs, each with the MCP tool and argument that reads it, and `views`). `full`: the whole dashboard with every series card. `catalog`: the series as rows without histories — { series: [{ key, title, unit, category, frequency, latest, latestPeriod, stale, staleAfterDays, source }], total, offset, limit, nextOffset, categories }; `stale` is true when `latestPeriod` is older than the series' cadence allows (more than `staleAfterDays` days after the period's first day), null when the cadence is unknown. `economy`: one Economy sub-tab (`section`) as the page draws it — headline cards, its questions (modules) with their cards, charts and table, then the sub-tab's other series paged by `limit` / `offset` ({ total, limit, offset, hasMore, nextOffset }; `next_offset` is a deprecated copy of nextOffset); each card carries latest, prior and year-ago prints and change_1y; without `section`, the sub-tabs the country fills. `central_bank`: `section` overview | statistics | financials, built from series. `government`: the Government sections and the parts each is made of — per part `path` (the route that reads it) and `query` (its parameters, e.g. section=votes), plus `view` / `args` (the same part as get_government arguments). The profile leaves out the dashboard's always-empty placeholder fields (indices, fx, news, …); `full` keeps them.", "schema": { "type": "string", "enum": [ "profile", "full", "catalog", "economy", "central_bank", "government" ], "default": "profile" } }, { "name": "section", "in": "query", "description": "economy: growth_activity, labour_market, inflation_prices, consumption_households, housing_real_estate, credit_funding, trade_external, fx, energy, tourism_transport, industry_technology, fiscal. central_bank: overview, statistics, financials. catalog: an Economy sub-tab slug, to list the series that pane draws.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "catalog: words that must all appear in the title, key or publisher.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "catalog: one indicator category (output, prices, labor, rates, money, …).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "catalog: rows, 1–500 (default 100). economy / central_bank: other series per page, 0–200 (default 40).", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "catalog, economy, central_bank: rows to skip.", "schema": { "type": "integer" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_country", "get_economy", "get_central_bank", "list_macro_series", "get_macro_series", "get_government" ], "callable": true }, { "id": "get-regional-macro-series", "method": "GET", "path": "/api/v1/countries/{iso}/regions", "title": "Regional macro series", "description": "Macro series held for each first-level region of the country (the UAE's emirates). By default (`view=index`) each region's code, name, `seriesCount` and newest `latestPeriod`, with `views`. `view=full` serves the series as cards grouped by region (the same card as /countries/{iso}?view=full: latest, yoyChange, yoyChangeUnit, yearAgo, priorChange, a short sparkline and `source` { name, fullName, url, note }; about 400 KB for the UAE), or one region's with `region`. A card's full history is GET /api/v1/countries/{region}/series?key= with the region's ISO 3166-2 code (e.g. AE-DU). An unknown `region` is a 404. `parent` (a first-level region, e.g. DE-BY) reads the second level under it instead (Germany's Kreise, DE-KRS-09162, by Regionalschlüssel; Spain's or Italy's provinces, coded like ISO 3166-2, e.g. ES-SE): the same views, with `region` naming one of its sub-regions and the index carrying `parent`; a first-level region with none (Berlin) lists no regions.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`index` (default): the regions with series counts. `full`: every region's series as cards (`region` narrows to one). `catalog` with `region`: one region's series as rows without histories (same shape as /countries/{iso}?view=catalog).", "schema": { "type": "string", "enum": [ "index", "full", "catalog" ], "default": "index" } }, { "name": "region", "in": "query", "description": "full, catalog (required): the region's ISO 3166-2 code, e.g. AE-DU (with `parent`: a sub-region's code, e.g. DE-KRS-09162 or ES-SE).", "schema": { "type": "string" } }, { "name": "parent", "in": "query", "description": "A first-level region's ISO 3166-2 code (e.g. DE-BY): read the second-level regions under it.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "catalog: words that must all appear.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "catalog: one indicator category.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "catalog: rows, 1–500 (default 100).", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "catalog: rows to skip.", "schema": { "type": "integer" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_country", "list_macro_series" ], "callable": true }, { "id": "get-macro-series", "method": "GET", "path": "/api/v1/countries/{iso}/series", "title": "Macro series", "description": "History of one macro series (the current vintage: the latest published value for each period), uncapped unless `from` / `to` / `limit` bound it; the header names its title, `units` (as its values are scaled) and seasonal adjustment. Use this for any series the country dashboard shows as a card. Every value carries its provenance: `source` = { name (short publisher name), fullName, url (where it was retrieved), note (how it reached the platform) }, null when not recorded. A key the country or region does not hold is a 404 (`not_found`).", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 country code (US), ISO 3166-2 first-level region code (AE-DU) or second-level region code (DE-KRS-09162, ES-SE).", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "description": "Series key, A-Z0-9_ (e.g. UNEMPLOYMENT_RATE). Keys come from GET /api/v1/countries/{iso}?view=catalog (or /regions?view=catalog®ion= for a region, with &parent= for a second-level one).", "schema": { "type": "string", "pattern": "^[A-Z0-9_]{1,64}$" } }, { "name": "from", "in": "query", "description": "First period, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Last period, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Latest N observations inside [from, to], 1–100000; `window` then reports total, returned and `olderTo` (the `to` that reads the points before).", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_macro_series" ], "callable": true }, { "id": "get-macro-series-by-id", "method": "GET", "path": "/api/v1/macro/series/{seriesId}", "title": "Macro series by id", "description": "One macro series by its numeric id: its current-vintage history (all of it unless from / to / limit bound it), title, units, frequency, description, last period and `source` ({ name, fullName, url, note }). Use it for series an indicator key cannot address, such as a government entity's own series (`series[]` on GET /countries/{iso}/government/entities/{code}).", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "seriesId", "in": "path", "required": true, "description": "macro_series id (digits).", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "First period, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Last period, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Latest N observations inside [from, to]. 1–100000.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_macro_series" ], "callable": true }, { "id": "get-executive-orders", "method": "GET", "path": "/api/v1/countries/{iso}/government/executive-orders", "title": "Executive orders", "description": "Every executive order in the online Federal Register (1994 onward), grouped by the administration that signed it; searchable and paged, newest number first: { administrations, total, offset, limit, hasMore, nextOffset, orders, coverage: { held, firstNumber, lastNumber, missing (gaps between firstNumber and lastNumber only), newestDate, complete, note }, load }. `coverage.complete` is true only when the held range has no gaps AND the Federal Register lane is fresh (`load.stale` false): a stale lane may be missing orders signed after `newestDate`. An unknown `era` is a 400 naming the country's eras.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "era", "in": "query", "description": "Administration era code, e.g. US_ADMIN_TRUMP_47 (`administrations[].eraCode`).", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Title/abstract contains, or an EO number.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "1–200, default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-executive-order-monthly-counts", "method": "GET", "path": "/api/v1/countries/{iso}/government/executive-orders/monthly", "title": "Executive order monthly counts", "description": "Monthly counts of executive orders, other Federal Register presidential documents, and GovInfo compilation packages.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-legislation-monthly-counts", "method": "GET", "path": "/api/v1/countries/{iso}/government/bills/monthly", "title": "Legislation monthly counts", "description": "Monthly counts of measures first reaching each legislative stage: introduced, passed one chamber, cleared Congress, became law, vetoed.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "congress", "in": "query", "description": "Congress number (1–200), or all. Default: the newest held.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-government-entities", "method": "GET", "path": "/api/v1/countries/{iso}/government/entities", "title": "Government entities", "description": "Government entity registry (non-US countries, e.g. AE): the federal → emirate → entity tree with each entity's head and its counts of listed-company links and publications, plus per-region and overall counts. available=false while the registry holds nothing for the country. Each entity carries `logo` = { url, kind, width, height, sourcePage, sourceUrl, license } when its emblem is held. Paged in registry order: the first 50 entities by default, with `page` = { total, offset, limit, nextOffset }; `full=true` serves every entity (about 250 KB for AE). A level, kind or region the registry does not hold is a 400 naming the ones it does.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "level", "in": "query", "description": "Entity level, e.g. federal, emirate, free_zone, local.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "ISO 3166-2 region, e.g. AE-DU.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Entity kind, e.g. authority, ministry, regulator.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Words that must all appear in the entity's text fields (name, code, kind, level, head, …).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "full", "in": "query", "description": "true = the whole registry, unpaged. Does not combine with filters or paging.", "schema": { "type": "boolean", "default": false } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-government-entity", "method": "GET", "path": "/api/v1/countries/{iso}/government/entities/{code}", "title": "Government entity", "description": "One government entity: description, website, head, lineage and children; the listed companies it owns, regulates or grants a concession to (stake, evidence URL); and `notIngested[]`: the datasets it publishes that the platform does not hold yet (gov_entity_publication_coverage, not_ingested; datasets only, never press releases or landing pages) — { publicationId, kind, kindLabel, title, url, format, frequency, datasetRef, status, lastChecked, seriesCount, reason }; empty when every dataset is held. Each entity carries `logo` = { url, kind, width, height, sourcePage, sourceUrl, license } when its emblem is held. `legalDocuments[]`: the laws, decrees and regulations tied to the entity — { docId, role (issuer | establishes | administers | regulates | amends_mandate | mentions), docType, docTypeLabel, number, year, titleEn, titleAr, titleEnDisplay (official English title, else a machine translation), titleEnIsMachine, titleEnMachine, issueDate, effectiveDate, status, issuerEntityCode, issuerName, sourcePageUrl, pdfUrlEn, pdfUrlAr, summaryEn, companies: [{ cik, name, ticker, routeKey }] — the published companies the instrument affects (GET /companies/{id}/laws) }, establishing instruments first, then newest; empty when none are on record. `series[]`: the series the entity publishes as the macro cube holds them — { seriesId, indicatorCode, title, frequency, geoCode, units, publicationId, publicationTitle, groupLabel, sortOrder, lastPeriod, lastValue, snapshot }; each one's history is GET /api/v1/macro/series/{seriesId}, and a whole group's latest values, y/y and sparklines in one batch at GET …/entities/{code}/series?group=.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "gov_entity code, e.g. AE.DU.RTA.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`compact` (default): legal documents paged under `legalDocumentsPage` ({ total, offset, limit, nextOffset }), series replaced by `seriesCount`. `full`: every legal document and series (the RTA's is about 1.1 MB).", "schema": { "type": "string", "enum": [ "compact", "full" ], "default": "compact" } }, { "name": "limit", "in": "query", "description": "compact: legal documents per page, 1–200, default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "offset", "in": "query", "description": "compact: legal documents to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "description": "compact: words that must all appear in a legal document's text fields (title, number, issuer, type, summary, …). limit, offset or q with view=full is a 400.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-government-entity-series", "method": "GET", "path": "/api/v1/countries/{iso}/government/entities/{code}/series", "title": "Government entity series", "description": "The series a government entity publishes, one row each in a single batch: { entityCode, group, series: [{ seriesId, latest, latestPeriod, yearAgo, yearAgoPeriod, spark: [number] (the last values, up to 36, oldest first), source: { name, fullName, url, note } }] }, in the entity's own order. `group` narrows to one group — the series' groupLabel, else its publicationTitle, as on the entity's `series[]` (where each also carries lastValue and `snapshot` = true for a one-observation series). Current vintage, tombstones excluded. Full histories: GET /api/v1/macro/series/{seriesId}.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "gov_entity code, e.g. AE.DU.RTA.", "schema": { "type": "string" } }, { "name": "group", "in": "query", "required": false, "description": "Group label, e.g. Bus.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`catalog`: rows without sparklines, with title, unit and frequency — { series: [{ seriesId, title, unit, frequency, latest, latestPeriod, source }], total, offset, limit, nextOffset }.", "schema": { "type": "string", "enum": [ "full", "catalog" ], "default": "full" } }, { "name": "q", "in": "query", "description": "Words that must all appear (catalog; and full when paged).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "catalog: rows, 1–500 (default 100). full: rows, 1–200; default 50 without `group`, the whole group with it. A paged reply adds total, offset, limit, hasMore and nextOffset.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "description": "Rows to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "category", "in": "query", "description": "With view=catalog: only series in this category.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_macro_series" ], "callable": true }, { "id": "get-government-entity-logo", "method": "GET", "path": "/api/v1/countries/{iso}/government/entities/{code}/logo", "title": "Government entity logo", "description": "A government entity's emblem (SVG or PNG), as published by the entity — each entity's `logo` on the registry carries its source page and licence. 404 when none is held.", "groups": [ "Macro" ], "tier": "public", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "Entity code (e.g. AE.DU.RTA).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "image/*" ], "mcp_tools": [], "callable": true }, { "id": "get-government-data", "method": "GET", "path": "/api/v1/countries/{iso}/government/{view}", "title": "Government data", "description": "US government data from the platform's gov_* lanes: congress (members, committee rosters, meetings with witnesses, hearings, House roll-call votes), legislation (bills with sponsors, cosponsors, actions, subjects), executive (presidential documents, GovInfo packages), regulation (Federal Register rules and Regulations.gov dockets), spending (USAspending awards, recipients, agency totals) or feed (the newest 40 dated events; events are dated no later than today except scheduled committee meetings, up to 120 days ahead, which carry `scheduled: true`). Without `section` the reply is bounded: every section's first 20 rows, a `pages` block per section ({ total, offset, limit, nextOffset }) and a `note`; `full=true` serves every row (congress is about 1.3 MB). Paged rows are compact: a committee carries `seatCount` and its subcommittees' codes and names, a roll-call vote no member positions (GET …/government/votes/{congress}/{chamber}/{session}/{roll} has them), a recipient group `recipientEntities` (a count). `load` says how complete and how fresh the rows are: `isSample` (a pilot load), `inProgress`, `lastLoadedAt`, `stale` (some lane has not loaded within its publisher's cadence, 3 days for daily publishers), `staleLanes` and `failedLanes` (as source/lane). Non-US countries return available=false.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "view", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "congress", "legislation", "executive", "regulation", "spending", "feed" ] } }, { "name": "chamber", "in": "query", "description": "congress only: house, senate, joint or all (default all). Passing it with any other view is a 400.", "schema": { "type": "string", "enum": [ "house", "senate", "joint", "all" ], "default": "all" } }, { "name": "section", "in": "query", "description": "Row arrays of the view to page, comma-separated (congress: members, committees, meetings, hearings, votes; legislation: bills; executive: presidential, packages; regulation: rules, dockets; spending: awards, recipients, byAgency; feed: events); the others are left out. Paging without section is a 400.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per section, 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip per section.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "description": "Words that filter each section's rows.", "schema": { "type": "string" } }, { "name": "full", "in": "query", "description": "true = every row of every section, uncompacted (the terminal's panels). Does not combine with section, limit, offset or q.", "schema": { "type": "boolean", "default": false } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-judiciary-data", "method": "GET", "path": "/api/v1/countries/{iso}/judiciary/{view}", "title": "Judiciary data", "description": "US judiciary: the Supreme Court's docket, opinions and orders (scotus), the courts below it (courts), judges, opinions and advocates. Non-US countries return available=false.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "view", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "scotus", "courts", "judges", "opinions", "advocates" ] } }, { "name": "section", "in": "query", "description": "Row arrays of the view to page, comma-separated; the others are left out. scotus: inProgress, decided, precedent, recentOrders, terms. courts: tiers, byState, federalAppellate, federalDistricts, stateSupreme, prosecutors. judges: tiers, byPresident, recent, supremeCourt. opinions: byCourt, byNatureSuit, recent. advocates: topByCases, topFirms. limit, offset or q without section is a 400.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Rows per section, 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip per section.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "description": "Words that filter each section's rows.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-office-changes", "method": "GET", "path": "/api/v1/countries/{iso}/officials/changes", "title": "Office changes", "description": "Arrivals and departures in public office, by era (administration, or central-bank chair), with the seats awaiting confirmation.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "Which bodies. Default government.", "schema": { "type": "string", "enum": [ "government", "central_bank" ] } }, { "name": "since", "in": "query", "description": "Changes effective on or after, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "description": "Changes effective on or before, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "era", "in": "query", "description": "One era code.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Arrivals or departures.", "schema": { "type": "string", "enum": [ "arrival", "departure" ] } }, { "name": "q", "in": "query", "description": "Words in the name, title or office.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-presidential-schedule", "method": "GET", "path": "/api/v1/countries/{iso}/officials/schedule", "title": "Presidential schedule", "description": "The sitting US president's week (Sunday–Saturday, America/New_York), from BNO News' compilation of the White House press-pool schedule: a third-party source, not an official White House release. Other countries return available=false.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Any day in the week, YYYY-MM-DD; defaults to today in America/New_York.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-country-officials", "method": "GET", "path": "/api/v1/countries/{iso}/officials", "title": "Country officials", "description": "Public officeholders from the people registry: executive cabinet, central-bank board, regional bank presidents. Defaults to the sitting era. An unknown `body` or `era` is a 400 naming the country's. With `limit` / `offset` the holders are paged in roster order: { eraCode, bodies (every body with its holder count), rosters (this page's holders), eras, total, offset, limit, hasMore, nextOffset }.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "era", "in": "query", "description": "Step to a past administration or chair era; the roster is read at that era's last day.", "schema": { "type": "string" } }, { "name": "body", "in": "query", "description": "Office body codes, comma-separated, up to 20 (e.g. AE_CBUAE_BOARD): only those rosters and eras.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Holders per page, 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Holders to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government" ], "callable": true }, { "id": "get-federal-reserve-financials", "method": "GET", "path": "/api/v1/countries/{iso}/fed-financials", "title": "Federal Reserve financials", "description": "The Federal Reserve Banks' balance sheet and income statement (United States only).", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "entity", "in": "query", "description": "`combined` (default) or one Reserve Bank.", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Column cadence.", "schema": { "type": "string", "enum": [ "annual", "quarterly" ], "default": "annual" } }, { "name": "statement", "in": "query", "description": "One statement.", "schema": { "type": "string", "enum": [ "balance_sheet", "income_statement", "income_summary" ] } }, { "name": "from", "in": "query", "description": "First period end, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last period end, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "last", "in": "query", "description": "Newest N columns in the window, 1–200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_central_bank", "get_central_bank_financials" ], "callable": true }, { "id": "get-federal-reserve-financial-notes", "method": "GET", "path": "/api/v1/countries/{iso}/fed-financials/notes", "title": "Federal Reserve financial notes", "description": "The notes to one Federal Reserve financial-statement document as tables, figures shown only for tables that pass their checks (United States only). By default an index: { entity, view: \"index\", documents, document, tables: [{ id, noteNumber, noteTitle, tableTitle, caption, unitScale, page, status, holdReason, rowCount }] } without figures; `table=` serves that table with its figures; `view=full` every table with its figures (about 400 KB). Each document's `held` (also `withheldTables`) counts the tables a check withheld; 0 means none was withheld.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "entity", "in": "query", "description": "`combined` (default) or one Reserve Bank.", "schema": { "type": "string" } }, { "name": "doc_id", "in": "query", "description": "One document.", "schema": { "type": "integer" } }, { "name": "period_end", "in": "query", "description": "The document for this period end, YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Cadence.", "schema": { "type": "string", "enum": [ "annual", "quarterly" ], "default": "annual" } }, { "name": "table", "in": "query", "description": "Only this note table, with its figures (404 when the document has none).", "schema": { "type": "integer" } }, { "name": "view", "in": "query", "description": "`index` (default): tables without figures. `full`: every table with its figures.", "schema": { "type": "string", "enum": [ "index", "full" ], "default": "index" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_central_bank_financials" ], "callable": true }, { "id": "get-armed-conflicts", "method": "GET", "path": "/api/v1/military/conflicts", "title": "Armed conflicts", "description": "The armed conflicts published from the registry (UCDP/PRIO 1946–2024 plus sourced seeds): span, type, region, intensity, battle deaths and the states on either side. Published so far: the 2026 Iran war, the 2026 Houthi–Saudi war, the 2025–2026 Afghanistan–Pakistan war and the Russia–Ukraine war; the rest of the registry is under review. Any filter switches to a page.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "country", "in": "query", "description": "ISO alpha-2 state that took part, either side.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "One of africa, americas, asia, europe, global, middle_east, oceania.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Conflict types, comma-separated, from interstate, intrastate, internationalized_intrastate, extrasystemic, operation, crisis.", "schema": { "type": "string" } }, { "name": "active_in", "in": "query", "description": "A year (1800–2100) the conflict was active in.", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "description": "First day (conflicts overlapping the window), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "ongoing", "in": "query", "description": "1 or true: only ongoing conflicts. 0 or false: only ended ones. Any other value is a 400.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Words that must all appear in the conflict's name or location.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_conflicts" ], "callable": true }, { "id": "get-country-armed-forces", "method": "GET", "path": "/api/v1/military/countries/{iso2}", "title": "Country armed forces", "description": "A country's armed forces, for a country with a Military page (the US, the UAE, Saudi Arabia, …; any other is a 404): the head of state and ministers who command them (`principals`, each under its military title), the military leadership seats with their holders, rank, start date and source page (`leaders`), defence spending by year (`spending`: SIPRI military expenditure in US dollars, as a share of GDP and of government spending, IISS armed forces personnel, all via World Bank WDI, plus the country's own budget line where it publishes one, converted to dollars), and counts of the published conflicts it took part in (`conflicts`). A year a source does not hold is absent, never zero.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso2", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. SA).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-country-conflicts", "method": "GET", "path": "/api/v1/military/countries/{iso2}/conflicts", "title": "Country conflicts", "description": "The published armed conflicts a country took part in, from its side: its role (primary party, or supporting with its own troops), its years, whom it faced, the conflict's type, intensity and battle deaths. Only published conflicts serve (as on /military/conflicts). Any filter switches to a page; `counts` stay those of every listed conflict.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso2", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. SA).", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "One of africa, americas, asia, europe, global, middle_east, oceania.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Conflict types, comma-separated, from interstate, intrastate, internationalized_intrastate, extrasystemic, operation, crisis.", "schema": { "type": "string" } }, { "name": "active_in", "in": "query", "description": "A year (1800–2100) the conflict was active in.", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "description": "First day (conflicts overlapping the window), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "ongoing", "in": "query", "description": "1 or true: only ongoing conflicts. 0 or false: only ended ones. Any other value is a 400.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Words that must all appear in the conflict's name or location.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–500.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-international-organisations", "method": "GET", "path": "/api/v1/foreign-relations/organisations", "title": "International organisations", "description": "Every international organisation in the registry (UN bodies, development banks, standard setters, alliances, blocs, forums) with how many countries sit in it today. Any filter switches to a page.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "q", "in": "query", "description": "Words in the code, name or short name.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Organisation kind, e.g. development_bank.", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "Domain, e.g. finance.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_organisation" ], "callable": true }, { "id": "get-organisation-and-country", "method": "GET", "path": "/api/v1/foreign-relations/organisations/{code}/countries/{iso2}", "title": "Organisation and country", "description": "One organisation's relationship with one country (e.g. IMF–Pakistan): seats, measured series, financing instruments with their reviews, dated acts and, for the UN, treaties deposited.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Organisation code, e.g. IMF.", "schema": { "type": "string" } }, { "name": "iso2", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code.", "schema": { "type": "string" } }, { "name": "instrument_class", "in": "query", "description": "Financing instrument classes, comma-separated, e.g. loan,credit.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Financing instruments per page, 1–200, default 20, newest approval first; adds `financingPage`.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "offset", "in": "query", "description": "Financing instruments to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_organisation" ], "callable": true }, { "id": "get-policy-text-overview", "method": "GET", "path": "/api/v1/countries/{iso}/policy-text", "title": "Policy text overview", "description": "Central-bank text corpus summary: coverage, the newest release of each type and the concepts discussed (US Federal Reserve; UAE Central Bank). available=false for a country with no corpus.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_central_bank" ], "callable": true }, { "id": "get-policy-documents", "method": "GET", "path": "/api/v1/countries/{iso}/policy-text/documents", "title": "Policy documents", "description": "Policy document index.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "group", "in": "query", "description": "Document group: overview, decisions, statements, press-conferences, minutes, speeches, beige-book (Fed); base-rate-decisions, press-releases, public-statements, financial-stability, annual-reports, periodic-reports, research (CBUAE). Others are a 400.", "schema": { "type": "string" } }, { "name": "docType", "in": "query", "description": "Document type: fomc_statement, fomc_minutes, fomc_press_conference, fed_speech, beige_book, cbuae_base_rate_decision, cbuae_press_release, cbuae_public_statement, cbuae_financial_stability_report, cbuae_annual_report, cbuae_periodic_report, cbuae_research_paper. Others are a 400.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "description": "Calendar year, 1900–2100; any other value is a 400.", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100 } }, { "name": "speaker", "in": "query", "description": "Speaker name, exactly as stored (the page's picker).", "schema": { "type": "string" } }, { "name": "speakerWords", "in": "query", "description": "Words of the speaker's name, any order (e.g. Powell).", "schema": { "type": "string" } }, { "name": "district", "in": "query", "description": "Beige Book district.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Words in the title or speaker line only.", "schema": { "type": "string" } }, { "name": "text", "in": "query", "description": "Words in the documents' own text. Reads the newest documents passing the other filters, within a per-request budget, and answers { items (each with matchedIn, occurrences, snippets), scan: { candidates, offset, scanned, nextOffset, newest, oldest, unreadable, stoppedAtLimit } }; pass scan.nextOffset as offset to search older documents.", "schema": { "type": "string" } }, { "name": "analyzedOnly", "in": "query", "description": "1 = only documents with extracted observations.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "limit", "in": "query", "description": "Default 50, max 200; with text, default 20, max 50. Above the max is a 400.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "description": "Default 0. The list answers limit, offset, hasMore and nextOffset; a text scan answers scan.nextOffset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "subtype", "in": "query", "description": "Only documents of this subtype, as listed on each document (`subtype`).", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_central_bank", "search_policy_text" ], "callable": true }, { "id": "get-policy-document", "method": "GET", "path": "/api/v1/countries/{iso}/policy-text/documents/{documentId}", "title": "Policy document", "description": "One policy document: its full text (document.txt) and every servable observation on it, each with character offsets into that text.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_policy_document" ], "callable": true }, { "id": "get-beige-book-districts", "method": "GET", "path": "/api/v1/countries/{iso}/policy-text/districts", "title": "Beige Book districts", "description": "Beige Book district breakdown, newest release first.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Releases, 1–24, default 8.", "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 8 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_central_bank" ], "callable": true }, { "id": "get-policy-guidance", "method": "GET", "path": "/api/v1/countries/{iso}/policy-text/guidance", "title": "Policy guidance", "description": "Forward-guidance observations from policy text, newest first.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Readings, 1–50, default 8.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 8 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_central_bank" ], "callable": true }, { "id": "get-list-benchmarks", "method": "GET", "path": "/api/v1/indices", "title": "List benchmarks", "description": "Benchmark indices and sector ETFs. With `vs`, prices and returns are converted into that currency at the exchange rate on each figure's own dates (`currency` then reads `vs`; `listing_currency` keeps the exchange's); 30-day volatility stays in the listing currency.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "vs", "in": "query", "description": "Fiat ISO code to price in, e.g. USD or EUR (any currency on the FX board). Omit for each listing's own currency.", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-benchmark-sparklines", "method": "GET", "path": "/api/v1/indices/sparklines", "title": "Benchmark sparklines", "description": "Batch benchmark sparklines, keyed by uppercase registry symbol. Each array contains the same listing-currency closes as the 2Y prices route, including its up-to-200-bar moving-average lookback prefix. Unknown, inactive and unpriced symbols are omitted.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "symbols", "in": "query", "description": "Up to 64 index symbols total, comma-separated or repeated, e.g. SPY,QQQ. Empty or absent symbols return an empty map. Each registry symbol is 1–16 letters, digits, dots, underscores or dashes and starts with a letter or digit.", "schema": { "type": "array", "maxItems": 64, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,15}$" } }, "style": "form", "explode": false } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-benchmark-detail", "method": "GET", "path": "/api/v1/indices/{symbol}", "title": "Benchmark detail", "description": "One benchmark.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Index / ETF symbol, e.g. SPY.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-benchmark-prices", "method": "GET", "path": "/api/v1/indices/{symbol}/prices", "title": "Benchmark prices", "description": "Daily bars for a benchmark.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Index / ETF symbol.", "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "Lookback window.", "schema": { "type": "string", "enum": [ "1M", "3M", "6M", "YTD", "1Y", "2Y", "5Y", "ALL" ], "default": "1Y", "x-case-insensitive": true } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-list-commodities-compute", "method": "GET", "path": "/api/v1/commodities", "title": "List commodities & compute", "description": "Commodity and compute instruments (including GPU rental prices). World Bank Pink Sheet rows carry an `attribution` (CC BY 4.0) to display.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "asset_class", "in": "query", "description": "Which asset class to list; one class per call, because the columns differ (a compute row carries a GPU spec sheet, a physical row carries a benchmark and unit).", "schema": { "type": "string", "enum": [ "compute", "energy", "metals", "agriculture", "other" ], "default": "compute" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_market_board" ], "callable": true }, { "id": "get-commodity-fundamentals", "method": "GET", "path": "/api/v1/commodities/fundamentals", "title": "Commodity fundamentals", "description": "Non-price commodity series for an asset class — US petroleum inventories and crude production (EIA WPSR) — with the change on the previous report, on a year earlier, and vs the five-year average.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "asset_class", "in": "query", "description": "Asset class. Default energy.", "schema": { "type": "string", "enum": [ "energy", "metals", "agriculture", "other" ], "default": "energy" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_commodity_analytics" ], "callable": true }, { "id": "get-commodity-market-map", "method": "GET", "path": "/api/v1/commodities/market-map", "title": "Commodity market map", "description": "The commodity market map: the sector tree (energy, precious and industrial metals, grains, softs, livestock, fertilizers, compute) with each node's price drivers and quoting convention, and under it every benchmark, grade and product a professional terminal shows — with its exchange contract, price-reporting agency, the benchmark a grade is quoted against, and `coverage`: what the platform carries for it (futures > daily > weekly > monthly > pending > not_carried). Energy is mapped first.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "asset_class", "in": "query", "description": "Limit to one asset class; omit for the whole tree.", "schema": { "type": "string", "enum": [ "compute", "energy", "metals", "agriculture", "other" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_commodity_analytics" ], "callable": true }, { "id": "get-commodity-futures-curves", "method": "GET", "path": "/api/v1/commodities/futures", "title": "Commodity futures curves", "description": "Continuation futures curves: NYMEX WTI (CL), RBOB (RB), NY Harbor ULSD (HO) and Henry Hub (NG) settlements by position (1 = nearest-expiring), from a CME end-of-day feed. Returns no curves until that feed is licensed and loaded. Contract 1 is the nearest-expiring contract through its last trading day. Each position carries its latest and previous settle and the same position a week and a month earlier.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "asset_class", "in": "query", "description": "Limit to one asset class; omit for all.", "schema": { "type": "string", "enum": [ "compute", "energy", "metals", "agriculture", "other" ] } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-commodity-spreads-ratios", "method": "GET", "path": "/api/v1/commodities/spreads", "title": "Commodity spreads & ratios", "description": "Spreads & ratios for an asset class — crack spreads (3-2-1, gasoline, diesel, jet), Brent–WTI, Brent–Dubai, WCS–WTI, TTF–Henry Hub, gold/silver, copper/gold, soybean/corn, the soybean crush and more — computed from their legs' published prices, only on dates where every leg printed (monthly spreads average each leg by month). Each carries its definition, legs, latest value, previous value, 52-week range and history: by default each history's last year, with a `window` block (`olderTo` reads further back); `view=full` serves five years.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "asset_class", "in": "query", "description": "Asset class.", "schema": { "type": "string", "enum": [ "energy", "metals", "agriculture" ], "default": "energy" } }, { "name": "key", "in": "query", "description": "One spread, e.g. BRENT_WTI: uppercase letters, digits and _ (else 400); unknown key 404.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "description": "`summary`: latest figures, no history. Cannot be combined with from, to, limit or frequency (400). `full`: every spread with its five-year history (no window). Omit for each history's last year.", "schema": { "type": "string", "enum": [ "summary", "full" ] } }, { "name": "from", "in": "query", "description": "First day of each history, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last day of each history, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Latest N points of each history, 1–100000; `window.olderTo` reads further back.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "frequency", "in": "query", "description": "Bar frequency: daily (the default), weekly or monthly (the last close of each week or month).", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_commodity_analytics" ], "callable": true }, { "id": "get-commodity-positioning-cftc-cot", "method": "GET", "path": "/api/v1/commodities/positioning", "title": "Commodity positioning (CFTC COT)", "description": "CFTC Commitments of Traders (disaggregated, futures only) for the asset class's futures markets: managed-money and producer net positions, week-on-week change, share of open interest, position in the three-year range, and the weekly managed-money history. Positions at Tuesday's close, published Friday 15:30 ET.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "asset_class", "in": "query", "description": "Asset class; all (default) = every class with a futures market on file.", "schema": { "type": "string", "enum": [ "all", "compute", "energy", "metals", "agriculture", "other" ], "default": "all" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_commodity_analytics" ], "callable": true }, { "id": "get-instrument-detail", "method": "GET", "path": "/api/v1/commodities/{symbol}", "title": "Instrument detail", "description": "One instrument with spec and venues. An unknown symbol is a 404.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Instrument symbol.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_market_series" ], "callable": true }, { "id": "get-instrument-prices", "method": "GET", "path": "/api/v1/commodities/{symbol}/prices", "title": "Instrument prices", "description": "Daily bars for an instrument (close-only: open, high and low repeat the close; volume is 0). Bars run from the first trading day of `range` to the latest; `lookback` adds earlier bars for moving averages. `coverageFrom` is the first day held; `note` says when the history starts after the range's first day or no bar falls inside it. Bar times `t` are epoch ms at UTC midnight. An unknown symbol is a 404.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Instrument symbol.", "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "Window of bars served: from the range's first day (1M = 31 days back, YTD = 1 January) to the latest bar; ALL is the whole history. `rangeFrom` echoes the first day; `displayFrom` is the epoch ms of the first bar inside the range.", "schema": { "type": "string", "enum": [ "1M", "3M", "6M", "YTD", "1Y", "2Y", "5Y", "ALL" ], "default": "1Y", "x-case-insensitive": true } }, { "name": "lookback", "in": "query", "description": "Bars to add before the range's first day, e.g. 200 to draw a 200-day moving average from the first bar. Default 0: only bars inside the range. `lookbackBars` says how many were added.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 } }, { "name": "from", "in": "query", "description": "First day (default the range's first day), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Latest N bars in the window, 1–100000. With from, to, limit or frequency only the window's bars are served, plus `window` and `instrument` blocks; `lookback` does not apply.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "frequency", "in": "query", "description": "Bar frequency: daily (the default), weekly or monthly (the last close of each week or month).", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_market_series" ], "callable": true }, { "id": "get-instrument-mentions", "method": "GET", "path": "/api/v1/commodities/{symbol}/mentions", "title": "Instrument mentions", "description": "Earnings-call mentions of the instrument, newest first, at most 10. Mentions are tracked for GPU instruments only; for any other instrument `mentions` is empty and `tracked` is false. An unknown symbol is a 404.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Instrument symbol.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_commodity_analytics" ], "callable": true }, { "id": "get-fx-reference-rates", "method": "GET", "path": "/api/v1/fx", "title": "FX reference rates", "description": "FX reference-rate board: every fiat currency against USD (units per 1 USD) at the latest complete weekday, the session before and 1W–10Y back, with two years of weekly closes (Frankfurter central-bank blend).", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "base", "in": "query", "description": "ISO 4217 code: the board re-based on this currency (units per 1 base, the base's return against each); unknown currency 404.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "With base: one region.", "schema": { "type": "string", "enum": [ "majors", "europe", "middle_east", "asia_pacific", "americas", "africa", "other" ] } }, { "name": "codes", "in": "query", "description": "With base: ISO 4217 codes, comma-separated, up to 60.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_market_board" ], "callable": true }, { "id": "get-fx-pair-prices", "method": "GET", "path": "/api/v1/fx/pairs/{pair}/prices", "title": "FX pair prices", "description": "Daily closes of one currency pair (units of the quote per 1 base; close-only, volume 0). Bars run from the first trading day of `range` to the latest; `lookback` adds earlier bars for moving averages. `coverageFrom` is the first day held; `note` says when the history starts after the range's first day or no bar falls inside it. Bar times `t` are epoch ms at UTC midnight. A pair with no rates held is a 404.", "groups": [ "Market Data" ], "tier": "free", "parameters": [ { "name": "pair", "in": "path", "required": true, "description": "Two ISO 4217 codes, e.g. USDCAD.", "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "Window of bars served: from the range's first day (1M = 31 days back, YTD = 1 January) to the latest bar; ALL is the whole history. `rangeFrom` echoes the first day; `displayFrom` is the epoch ms of the first bar inside the range.", "schema": { "type": "string", "enum": [ "1M", "3M", "6M", "YTD", "1Y", "2Y", "5Y", "ALL" ], "default": "1Y", "x-case-insensitive": true } }, { "name": "lookback", "in": "query", "description": "Bars to add before the range's first day, e.g. 200 to draw a 200-day moving average from the first bar. Default 0: only bars inside the range. `lookbackBars` says how many were added.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 } }, { "name": "from", "in": "query", "description": "First day (default the range's first day), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last day, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Latest N bars in the window, 1–100000. With from, to, limit or frequency exactly the window's bars are served, plus a `window` block; `lookback` does not apply.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "frequency", "in": "query", "description": "Bar frequency: daily (the default), weekly or monthly (the last close of each week or month).", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_market_series" ], "callable": true }, { "id": "get-people-registry", "method": "GET", "path": "/api/v1/people", "title": "People registry", "description": "People registry: corporate insiders (Section 16), government officeholders and central bankers. Paged: the body carries `rows`, `total`, `limit`, `offset`, `hasMore` and `nextOffset` (null on the last page), and for the corporate segment `asOf` (when the registry rollup was read; it is cached for ten minutes). Every value is checked: a bad one is a 400 naming it.", "groups": [ "Ownership & Insiders" ], "tier": "free", "parameters": [ { "name": "search", "in": "query", "description": "Name or ticker contains (case-insensitive); at most 200 characters.", "schema": { "type": "string" } }, { "name": "segment", "in": "query", "description": "Population.", "schema": { "type": "string", "enum": [ "corporate", "government", "central_bank" ], "default": "corporate" } }, { "name": "ticker", "in": "query", "description": "People with a seat at this company (exact ticker).", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Subset of corporate filers: people (humans only), officers, directors, institutions. Ignored for segment=government|central_bank.", "schema": { "type": "string", "enum": [ "people", "officers", "directors", "institutions" ], "default": "people" } }, { "name": "currentOnly", "in": "query", "description": "1 = only people with a seat filing in the last two years (officials: in office now).", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ], "default": "0" } }, { "name": "sort", "in": "query", "description": "Order; every order ends on the CIK, so offset paging is stable. Corporate segment only (officials are listed in their institution's chart order).", "schema": { "type": "string", "enum": [ "featured", "recent", "name", "companies", "accuracy" ], "default": "featured" } }, { "name": "limit", "in": "query", "description": "Page size, 1–200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip: the previous `nextOffset`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "universe", "in": "query", "description": "0 leaves out the `universe` block (registry-wide counts; null when left out).", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ], "default": "1" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "search_people" ], "callable": true }, { "id": "get-person-profile", "method": "GET", "path": "/api/v1/people/{cik}", "title": "Person profile", "description": "One person: roles, tenure, holdings.", "groups": [ "Ownership & Insiders" ], "tier": "free", "parameters": [ { "name": "cik", "in": "path", "required": true, "description": "Reporting-owner CIK.", "schema": { "type": "string" } }, { "name": "sections", "in": "query", "description": "Comma-separated: roles, insider, scorecard, statements, speech, shareholder_votes, leadership, office. Without it the whole person.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "With sections: page size of the long lists (predictions, statementCalls, votes, leadershipEvents), 1–100, default 20. Without sections, limit/offset are a 400.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "With sections: rows to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_person" ], "callable": true }, { "id": "get-person-photo", "method": "GET", "path": "/api/v1/people/{cik}/photo", "title": "Person photo", "description": "Person photo.", "groups": [ "Ownership & Insiders" ], "tier": "public", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "image/*" ], "mcp_tools": [], "callable": true }, { "id": "get-person-transactions", "method": "GET", "path": "/api/v1/people/{cik}/transactions", "title": "Person transactions", "description": "Insider transactions filed by this person.", "groups": [ "Ownership & Insiders" ], "tier": "free", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–100, default 20. Newest first.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Offset.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "from", "in": "query", "description": "First transaction date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last transaction date, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "codes", "in": "query", "description": "Form 4 transaction codes, comma-separated, e.g. P,S.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_person" ], "callable": true }, { "id": "get-executive-leaderboard", "method": "GET", "path": "/api/v1/scorecards/executives", "title": "Executive leaderboard", "description": "Executive credibility leaderboard (guidance kept vs missed).", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_guidance" ], "callable": true }, { "id": "get-executive-scorecard", "method": "GET", "path": "/api/v1/scorecards/executives/{name}", "title": "Executive scorecard", "description": "One executive's scorecard.", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_guidance" ], "callable": true }, { "id": "get-scored-earnings-events", "method": "GET", "path": "/api/v1/scorecards/events", "title": "Scored earnings events", "description": "Earnings events with guidance outcomes, newest event first. `newestEventDate` and `newestEventAgeDays` say how current the scored set is; `stalenessNote` appears when the newest scored event is more than 45 days old (later calls are not scored yet).", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "ticker", "in": "query", "description": "Filter by ticker.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Events, 1–1000, default 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } }, { "name": "withCommitments", "in": "query", "description": "true = only events where at least one guidance commitment came due. It does not embed commitments; read them from /scorecards/events/{id}.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_guidance" ], "callable": true }, { "id": "get-scored-event-detail", "method": "GET", "path": "/api/v1/scorecards/events/{id}", "title": "Scored event detail", "description": "One scored earnings event.", "groups": [ "Guidance & Scorecards" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_guidance" ], "callable": true }, { "id": "get-narrative-pulse", "method": "GET", "path": "/api/v1/intelligence/pulse", "title": "Narrative pulse", "description": "What changed this week: lifecycle transitions, breadth spikes, momentum movers and newly tested causal claims; tickers or sector narrow it to themes those companies raised. Both optional. An empty `items` carries `emptyReason` (e.g. while a management-commentary release serves themes, the registry ranking is not computed).", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "tickers", "in": "query", "description": "Comma-separated tickers.", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "description": "Sector name.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_themes" ], "callable": true }, { "id": "get-list-narratives", "method": "GET", "path": "/api/v1/intelligence/narratives", "title": "List narratives", "description": "Search, filter and sort the narrative registry (company and policy themes; dormant ones with includeDormant=1). Paged: the body carries `total`, `limit`, `offset`, `hasMore` and `nextOffset`; an empty list carries `emptyReason` (which catalog serves and whom it covers). An unknown `sort`, `source`, `themeScope` or `lifecycle`, or a number out of range, is a 400 naming the parameter.", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "search", "in": "query", "description": "Free text over name and description.", "schema": { "type": "string" } }, { "name": "sector", "in": "query", "description": "GICS sector name.", "schema": { "type": "string" } }, { "name": "tickers", "in": "query", "description": "Comma-separated tickers to scope by.", "schema": { "type": "string" } }, { "name": "countries", "in": "query", "description": "Comma-separated ISO alpha-2 issuer domiciles to scope by (e.g. AE,SA,QA,KW).", "schema": { "type": "string" } }, { "name": "ciks", "in": "query", "description": "Comma-separated issuer platform keys to scope by.", "schema": { "type": "string" } }, { "name": "includeDormant", "in": "query", "description": "1 to include themes with no activity in the trailing window (returned as lifecycleState=dormant); 0 (default) leaves them out.", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "minBreadth", "in": "query", "description": "Minimum companies discussing the theme, 0–50 (default 0 = long tail). Not applied to company or regional themes.", "schema": { "type": "integer", "minimum": 0, "maximum": 50, "default": 0 } }, { "name": "source", "in": "query", "description": "all (default), companies or policy.", "schema": { "type": "string", "enum": [ "all", "companies", "policy" ] } }, { "name": "sort", "in": "query", "description": "relevance (default), breadth, momentum or recent.", "schema": { "type": "string", "enum": [ "relevance", "breadth", "momentum", "recent" ], "default": "relevance" } }, { "name": "limit", "in": "query", "description": "Page size, 1–200, default 40.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 40 } }, { "name": "offset", "in": "query", "description": "Rows to skip (the previous `nextOffset`), default 0. 0–1000000, default 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } }, { "name": "activeOnly", "in": "query", "description": "1 lists only narratives mentioned in the last 28 days.", "schema": { "type": "string", "enum": [ "1", "0" ] } }, { "name": "lifecycle", "in": "query", "description": "Only narratives in this lifecycle state.", "schema": { "type": "string", "enum": [ "emerging", "accelerating", "broadening", "steady", "mature", "fading", "dormant" ] } }, { "name": "themeScope", "in": "query", "description": "Theme breadth: market-wide, regional or single-company themes; default all.", "schema": { "type": "string", "enum": [ "all", "market", "regional", "company" ], "default": "all" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_themes" ], "callable": true }, { "id": "get-narrative-filter-options", "method": "GET", "path": "/api/v1/intelligence/narratives/facets", "title": "Narrative filter options", "description": "Filter options for narratives: issuer countries and issuers that are members of active themes, with theme counts.", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "countries", "in": "query", "description": "Comma-separated ISO alpha-2 codes; restricts the company list only.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "list_themes", "get_company_themes" ], "callable": true }, { "id": "get-narrative-detail", "method": "GET", "path": "/api/v1/intelligence/narratives/{id}", "title": "Narrative detail", "description": "One narrative: header, daily metrics, member issuers with join dates and quotes, sector spread and its claim-graph edges.", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "membersLimit", "in": "query", "description": "Members per page, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "membersOffset", "in": "query", "description": "Members to skip. 0–100000, default 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } }, { "name": "membersSort", "in": "query", "description": "Member order: joined (first joiner first, as served), mentions or recent.", "schema": { "type": "string", "enum": [ "joined", "mentions", "recent" ] } }, { "name": "quotesPerMember", "in": "query", "description": "Quotes per member, 0–30.", "schema": { "type": "integer", "minimum": 0, "maximum": 30 } }, { "name": "member", "in": "query", "description": "One issuer's CIK or platform key. Any members* parameter adds membersTotal, membersOffset and membersNextOffset.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_theme" ], "callable": true }, { "id": "get-company-intelligence", "method": "GET", "path": "/api/v1/intelligence/company/{id}", "title": "Company intelligence", "description": "Company intelligence summary: theme exposures, causal claims (`causalProfile`), the guidance credibility scorecard. An unknown or unpublished company is a 404 (`code` not_found).", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-company-claims", "method": "GET", "path": "/api/v1/intelligence/company/{id}/claims", "title": "Company claims", "description": "Causal claims made by or about the company. An unknown or unpublished company is a 404 (`code` not_found).", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-company-themes", "method": "GET", "path": "/api/v1/intelligence/company/{id}/themes", "title": "Company themes", "description": "Themes the company is exposed to. Paged: the body carries `total`, `limit`, `offset`, `hasMore` and `nextOffset`; without a paging parameter every caller gets the first 25 (most mentioned first). An empty list carries `emptyReason`; an unknown or unpublished company is a 404 (`code` not_found).", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Themes per page, 1–100, default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "description": "Rows to skip (the previous `nextOffset`), default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "sort", "in": "query", "description": "Theme order: mentions (default, as served), recent or breadth.", "schema": { "type": "string", "enum": [ "mentions", "recent", "breadth" ], "default": "mentions" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_company_themes" ], "callable": true }, { "id": "get-company-intelligence-presence", "method": "GET", "path": "/api/v1/intelligence/company/{id}/presence", "title": "Company intelligence presence", "description": "What the intelligence surfaces hold for the company, per facet: `facets.themes` (present, `source` commentary or registry, the live `release`, and `reason` when there are none) and `facets.claims` (present, `count` of span-verified causal claims). `hasIntelligence` = any facet holds something; `hasThemes` = the company is in a served theme. An unknown or unpublished company is a 404 (`code` not_found).", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-transcript-audio", "method": "GET", "path": "/api/v1/companies/{id}/transcripts/{transcriptId}/audio", "title": "Transcript audio", "description": "Earnings-call webcast audio (supports Range).", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "transcriptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "Call date YYYY-MM-DD.", "schema": { "type": "string" }, "required": true } ], "request_body": null, "response_types": [], "mcp_tools": [], "callable": true }, { "id": "get-transcript-video", "method": "GET", "path": "/api/v1/companies/{id}/transcripts/{transcriptId}/video/{file}", "title": "Transcript video", "description": "Earnings-call video as HLS VOD where one is stored (`hasVideo` in the index): `video.m3u8`, whose segment lines `vseg_NNNNN.ts?date=` are fetched from the same route; `sync.json`, when present, gives `audio_offset_seconds`, the seconds the video runs ahead of the audio recording.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "transcriptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file", "in": "path", "required": true, "description": "`video.m3u8`, `vseg_NNNNN.ts` or `sync.json`.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "description": "Call date YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } } ], "request_body": null, "response_types": [ "application/vnd.apple.mpegurl", "video/mp2t" ], "mcp_tools": [], "callable": true }, { "id": "get-tab-presence", "method": "GET", "path": "/api/v1/companies/{id}/tab-presence", "title": "Tab presence", "description": "Which data-dependent company tabs and sub-tabs have content (Management, Ownership, Filing Notes, Scorecard, Transactions, News/Events, Bonds, Map, Supply Chain). 404 for an unknown company.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "post-chart-series", "method": "POST", "path": "/api/v1/charting/series", "title": "Chart series", "description": "Resolve up to 8 chartable series (macro, fundamentals, stock/index/commodity prices) into aligned time series.", "groups": [ "Analytics" ], "tier": "free", "parameters": [], "request_body": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "series", "frequency" ], "properties": { "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "id", "descriptor", "transformation", "aggregation" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Caller-chosen label echoed back with the series." }, "descriptor": { "$ref": "#/components/schemas/ChartSeriesDescriptor" }, "transformation": { "$ref": "#/components/schemas/Transformation" }, "aggregation": { "type": "string", "enum": [ "mean", "last", "sum" ] } } } }, "frequency": { "type": "string", "enum": [ "native", "daily", "weekly", "monthly", "quarterly", "annual" ] }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" } } } } } }, "response_types": [ "application/json" ], "mcp_tools": [ "get_chart_series" ], "callable": true }, { "id": "get-series-catalog", "method": "GET", "path": "/api/v1/correlation/catalog", "title": "Series catalog", "description": "Series catalog: the macro indicators, fundamental metrics, companies, indices and commodities that POST /charting/series accepts. With `type`, only that part as {type, items, page}.", "groups": [ "Analytics" ], "tier": "free", "parameters": [ { "name": "type", "in": "query", "description": "One part of the catalog.", "schema": { "type": "string", "enum": [ "macro", "fundamentals", "prices", "indices", "commodities" ] } }, { "name": "q", "in": "query", "description": "Words in its rows.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1–500, default 50.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Rows to skip, default 0.", "schema": { "type": "integer" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_chart_series" ], "callable": true }, { "id": "get-central-bank-documents", "method": "GET", "path": "/api/v1/companies/{id}/central-bank", "title": "Central bank documents", "description": "Central Bank of the UAE documents that bear on the company (press releases, Base Rate decisions, public statements): where the text names it, or addresses the class of institution it is licensed as. Each carries the rule that tagged it and, for a name, the sentence. An unknown company is a 404.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_government_exposure" ], "callable": true }, { "id": "get-law-document-pdf", "method": "GET", "path": "/api/v1/companies/{id}/laws/{docId}/document", "title": "Law document (PDF)", "description": "The stored PDF of a law, decree or resolution linked to the company (the platform's copy of the Dubai Legislation Portal file), by the `docId` that /laws lists. 404 when the instrument is not linked to the company or no copy in that language is held.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "docId", "in": "path", "required": true, "description": "Instrument id from /companies/{id}/laws.", "schema": { "type": "string", "pattern": "^\\d{1,12}$" } }, { "name": "lang", "in": "query", "description": "Language of the copy.", "schema": { "type": "string", "enum": [ "ar", "en" ], "default": "ar" } } ], "request_body": null, "response_types": [ "application/pdf" ], "mcp_tools": [], "callable": true }, { "id": "get-fed-financial-statement-document", "method": "GET", "path": "/api/v1/countries/{iso}/fed-financials/documents/{docId}", "title": "Fed financial-statement document", "description": "One Federal Reserve financial-statement document, exactly as the Board published it (PDF or HTML), by the document id the fed-financials grid and its sources cite. United States only (other countries 404). Public-domain material.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "docId", "in": "path", "required": true, "description": "Document id from /fed-financials or /fed-financials/source.", "schema": { "type": "string", "pattern": "^\\d{1,9}$" } } ], "request_body": null, "response_types": [ "application/pdf", "text/html" ], "mcp_tools": [], "callable": true }, { "id": "get-policy-document-file-pdf", "method": "GET", "path": "/api/v1/countries/{iso}/policy-text/documents/{documentId}/file", "title": "Policy document file (PDF)", "description": "The stored original PDF of a central-bank document (the copy the platform keeps of what the bank published), for the long reports whose extracted text loses tables and layout. 404 when no PDF copy is held.", "groups": [ "Macro" ], "tier": "free", "parameters": [ { "name": "iso", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US).", "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "description": "documentId from /policy-text/documents.", "schema": { "type": "integer", "minimum": 1 } } ], "request_body": null, "response_types": [ "application/pdf" ], "mcp_tools": [], "callable": true }, { "id": "get-transcript-timeline", "method": "GET", "path": "/api/v1/companies/{id}/transcripts/{transcriptId}/timeline", "title": "Transcript timeline", "description": "When each speaker turn starts in the call's recording: `{ turns: [{ speaker, role, section, startSeconds, endSeconds }] }`, in call order. `turns` is empty when the call carries no timings.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticker symbol (e.g. NVDA), numeric SEC CIK (zero-padding optional), or the platform key of a non-SEC issuer (e.g. XSAU000001 — the `cik` field of the company payload). A bare ticker always resolves to the SEC registrant.", "schema": { "type": "string" } }, { "name": "transcriptId", "in": "path", "required": true, "description": "Transcript id from /companies/{id}/transcripts.", "schema": { "type": "string", "pattern": "^[\\w.-]{1,64}$" } }, { "name": "date", "in": "query", "description": "The call date from /companies/{id}/transcripts, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" }, "required": true } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_transcript" ], "callable": true }, { "id": "get-earnings-calendar-coverage", "method": "GET", "path": "/api/v1/earnings/coverage", "title": "Earnings calendar coverage", "description": "How far the earnings calendar covers each company: readiness, availability, monitoring state, the next date and how many upcoming periods are scheduled by the issuer or estimated, with a summary over the filtered set.", "groups": [ "Company Data" ], "tier": "free", "parameters": [ { "name": "cik", "in": "query", "description": "Numeric CIK (1–10 digits) or platform key: one company.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Company name or ticker contains; at most 100 characters.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Uppercase ISO alpha-2 market codes, comma-separated (e.g. AE,SA).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "offset", "in": "query", "description": "Rows to skip.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_calendar" ], "callable": true }, { "id": "get-topic-trends-on-calls", "method": "GET", "path": "/api/v1/transcripts/topic-trends", "title": "Topic trends on calls", "description": "One curated topic's mentions on earnings calls: the quarterly trend and the companies ranked by mentions in the latest quarter, paged (`total`, `limit`, `offset`, `hasMore`, `nextOffset`). A topic not counted recently answers 503 `upstream_unavailable` with `Retry-After` while the count runs (a cold count reads every call since 2020); retry then.", "groups": [ "Transcripts & Calls" ], "tier": "free", "parameters": [ { "name": "topic", "in": "query", "description": "Curated topic id.", "schema": { "type": "string", "enum": [ "ai", "tariffs", "rates", "energy" ], "default": "ai" } }, { "name": "from", "in": "query", "description": "First day of the first quarter shown (the quarter holding it); default the latest eight quarters, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Last day of the last quarter shown (the quarter holding it), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "description": "Company name or ticker contains; at most 80 characters.", "schema": { "type": "string" } }, { "name": "countries", "in": "query", "description": "ISO alpha-2 codes, comma-separated.", "schema": { "type": "string" } }, { "name": "ciks", "in": "query", "description": "CIKs or platform keys, comma-separated.", "schema": { "type": "string" } }, { "name": "tickers", "in": "query", "description": "Tickers, comma-separated, at most 200.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Companies to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Companies per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 40 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-featured-narratives", "method": "GET", "path": "/api/v1/intelligence/narratives/featured", "title": "Featured narratives", "description": "The dashboard's featured themes: `{ themes: null }` while the pinned registry picks apply; a list replaces them while a commentary release is live.", "groups": [ "Intelligence" ], "tier": "free", "parameters": [], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-narrative-sparklines", "method": "GET", "path": "/api/v1/intelligence/narratives/metrics", "title": "Narrative sparklines", "description": "Compact weekly metric series per narrative, for row sparklines: `{ sparklines }` keyed by narrative id.", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "ids", "in": "query", "description": "Narrative ids, comma-separated, at most 20; others are ignored.", "schema": { "type": "string" } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [], "callable": true }, { "id": "get-observation-context", "method": "GET", "path": "/api/v1/intelligence/observations/{id}/context", "title": "Observation context", "description": "The sentence before and after one observation's verbatim quote, cut from its source document (never crossing the speaker's turn). 404 when the context is not available.", "groups": [ "Intelligence" ], "tier": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Observation id (from annotations, narratives or claims).", "schema": { "type": "integer", "minimum": 1 } } ], "request_body": null, "response_types": [ "application/json" ], "mcp_tools": [ "get_central_bank" ], "callable": true } ], "mcp_tools": [ { "name": "search", "title": "Search companies, macro series and countries", "description": "Resolve a name to an entity. Start every flow here. Returns matching companies (with ticker AND CIK), macro series, countries, and also: `commodities` (`id` = instrument symbol, e.g. BRENT, HENRYHUB, GOLD; pass it to `get_market_series` with asset_class \"commodities\"; the row's `asset_class` is its market: energy, metals, agriculture or compute); `fx_pairs` (`id` = BASE+QUOTE in market order, e.g. EURUSD or USDAED; matched from \"eur/usd\", \"usd-aed\", a currency name such as \"dirham\" or an ISO code, a single currency quoted against USD; pass it to `get_market_series` with asset_class \"fx\", or its `base` to `get_market_board`); `people` (`id` = 10-digit CIK or registry key such as USFDP00005, for `get_person`; the row gives the current seat and where it is held); `conflicts` (`id` = ucdp: or seed:, for `get_conflict`); `organisations` (`id` = org code, e.g. IMF or OPEC_PLUS, for `get_organisation`); `bonds` (`id` = instrument id, for `screen_corporate_bonds` or `get_company_debt` with `instrument_id`; matched on issuer, ticker, the instrument's description, ISIN or CUSIP; only instruments outstanding today). Use the returned ticker or CIK as `id` in the company tools, and a series' `id` (GEO:KEY, e.g. AE:EIBOR_3M or AE-DU:POPULATION) as `series` in `get_macro_series`. Series cover every country and first-level region that holds data; narrow them with `country`. When a series is not found, list a country's catalog with `list_macro_series`. Prefer the CIK for companies that changed symbols or have multiple share classes. `interpretations` says what the whole query reads as, by plain rules, with a `target` per reading: `company` + `tab` (\"nvda earnings\"), `series` (\"uae inflation\"), `country`, or `conflict` (\"war in the middle east\"). A question or a topic is searched by its words: set `include_content` to add `content`, the matching news, market themes and call transcripts, found by words and by meaning (`relaxed` means no row had every word and meaning found nothing).", "paths": [ "/api/v1/search", "/api/v1/search/content" ] }, { "name": "get_coverage", "title": "Coverage inventory — what Astreus holds, market by market", "description": "What the platform covers RIGHT NOW, from the serving tables (refreshed hourly): published companies by sector and exchange; parsed filings by year and type; XBRL and segment fact counts; insider transactions, 13F rows and 8-K events; daily price bars; macro series and economies; earnings-call transcripts, verified observations, guidance commitments, narratives and claim edges; central-bank documents. `markets[]` gives, for every country served (US, Saudi Arabia, UAE, Kuwait, Qatar, Japan, Taiwan, Korea, the UK and Europe, …), its exchanges, company count, the earliest reporting period held, the median completeness score, served note tables, and for each data type — financial statements, segments & KPIs, report documents, filing notes, earnings releases, transcripts, audio, investor presentations, 13F holdings — the reporting periods held versus the periods that exist. Call this whenever the user asks what Astreus covers, how deep the history is, or whether a market or data type is available; never answer coverage questions from memory. Free to call (no key needed) and metered like one request.", "paths": [ "/api/v1/landing/coverage" ] }, { "name": "get_company", "title": "Company profile, key metrics, overview series, signals and private-company records", "description": "One company, by `view`. `profile` (default): identity (name, ticker, CIK, sector), listing data and key metrics (market cap, P/E, margins). `overview_series`: annual revenue and diluted EPS, free cash flow, the income-statement subtotals per fiscal year and quarter (revenue to net income), and debt, free cash flow and cash per period. `capital_structure`: cash, total debt and total equity per fiscal year end, oldest first. `signals`: deterministic signals from filings: insider open-market buys, director-election dissent, red-flag 8-K items, board interlocks, the latest 13F quarter's holder rotation, filing latency. `private` (a private company: pass its XPRV key from `search`, e.g. XPRV000001 OpenAI): profile, funding rounds and a count of every other part; `section` reads one part (kpis, deals, events, N-PORT fund `marks`, counterparty `claims` from other companies' filings, counterparties, models, sites, data_centres, peers), paged by `limit` / `offset`. `private_filed`: its SEC record: Form D offerings, third-party SPV feeder filings and fund-reported credit marks. Every metric served has passed per-company validation gates; a null field means the gate withheld it or the company never reported it — say 'not available', never 0. Cite each figure with its period and, where given, its accession. Fund marks and reported private valuations are not exchange quotes.", "paths": [ "/api/v1/companies/{id}", "/api/v1/companies/{id}/overview-series", "/api/v1/companies/{id}/capital-structure", "/api/v1/companies/{id}/signals", "/api/v1/supercycle/private/{slug}", "/api/v1/supercycle/private/{slug}/filed" ] }, { "name": "get_financials", "title": "Standardized financial statements", "description": "Standardized income statement, balance sheet and cash flow statement, built from SEC and exchange-published filings and served only after per-company validation gates pass. Periods come NEWEST FIRST by period end: `limit` periods (default 10) after skipping `period_offset`, plus the trailing-twelve-month column (TTM) where served; `periods` in the reply says how much history exists and `next_period_offset` reads the next older window. `statements` picks the sections: default the three primary statements; add \"ratios\" (valuation, margins, returns; `include_calc` adds each cell's formula and inputs), \"segments_kpis\" (segment breakdowns and operating KPIs from filings, results releases and investor presentations; paged by rows, with `index` listing its groups — narrow with `segments_groups` or `segments_match`, read on with `segments_offset`) or the as-filed XBRL trees (income_statement_reported, …; SEC filers only). `statements_available` lists what this company serves. `detail: true` adds the filer's own XBRL lines under each std: line. Every reply stays under 60 KB: when it would not, it carries fewer periods and `note` says how to read the rest. Fetch whole statements once, never line by line. Rows are keyed std: (std:revenue); columns are period labels whose end dates are in financials.period_meta. Values are the LATEST RESTATED vintage in `reporting_currency`; the originally-filed vintage is get_financials_as_filed. reporting_basis is a period basis, not a vintage: latest_restated (default) = discrete quarters, as_reported = cumulative year-to-date quarters as the interim filing prints them. A cell absent from `values` is withheld-by-gate or never reported: say 'not available', never 0; `withheld` names the cells a gate held and why. Before quoting any figure, cite it: call `get_fact_source` with the row key exactly as served and the column's period end date.", "paths": [ "/api/v1/companies/{id}/financials" ] }, { "name": "get_segment_revenue", "title": "Revenue by business segment or region", "description": "Latest fiscal-year revenue broken down by product or reportable business segment (view=business, default) or by geography (view=regional), as disclosed in the company's filings and reconciled to consolidated revenue. `label` names the axis actually served (Product / Segment / Region); for filers that report no revenue breakdown (insurers, banks, lessors) `metricKey` names the segment top line standing in (PREMIUMS_EARNED, NET_INTEREST_INCOME, …) and consolidatedRevenue is null. Items flagged isResidual are the synthesized remainder; isReconciling is the filer's intersegment-elimination line, not a segment. Segment data is gated like the statements: a null payload means withheld or not disclosed, not zero. Cite `source.accession` (SEC accession, or the source document for non-EDGAR issuers) and `source.sourceTag` when quoting; every cell of the `segments_kpis` section from get_financials can be traced with get_fact_source using statement=segments_kpis and the row key.", "paths": [ "/api/v1/companies/{id}/segment-revenue", "/api/v1/companies/{id}/regional-revenue" ] }, { "name": "get_fact_source", "title": "Trace a figure to its SEC filing (citation)", "description": "The citation tool. Resolves one statement line for one period back to the fact(s), the filing accession number (or the source document reference and printed page for issuers whose statements are PDFs), and the arithmetic it was derived from. Call this BEFORE quoting any figure from `get_financials`, and put the accession number and period end next to the number in your answer. `key` is the line's key exactly as the financials payload returned it (std:, e.g. std:revenue — a bare 'revenue' is not found) or a raw XBRL tag (e.g. us-gaap:Revenues); for the segments_kpis section it is the row key as served (seg:::::: or kpi::), and the provenance names whether the cell is a filed fact, a derived fourth quarter, a synthesized residual, the filer's elimination line, a note table, a deck slide or a results release. `end_date` is the column's period end date.", "paths": [ "/api/v1/companies/{id}/fact-source" ] }, { "name": "list_filings", "title": "Filing and document index", "description": "A company's documents, newest first, with per-form counts (`typeCounts`) — or, when `id` is omitted, the newest documents market-wide (SEC EDGAR and every exchange / regulator feed). SEC filings (10-K, 10-Q, 8-K, proxies, …) carry their accession number; documents published outside EDGAR (exchange disclosures, IR publications, EDINET / DART / ESEF reports) carry their document reference in the same `accessionNumber` field (e.g. DFM-EMAAR-2026Q2-FS, EMAARIR-2026Q2-PRES) with `documentKind` pdf and a `title`, under form codes FS-A (annual financial statements), FS-Q (interim statements), AR (annual or integrated report), PRES (presentation), PR (press release), AGM (general meeting), CGR (governance report), EC (earnings call), DISC (other disclosure), XBRL, OWN (ownership). With `id`: filter with `types` (exact form codes, comma-separated; `typeCounts` lists the company's). Market-wide: filter with `family` (annual = 10-K, 20-F, 40-F, FS-A, AR; interim = 10-Q, FS-Q; current = 8-K, 6-K, DISC; press = PR; insider = Forms 3/4/5; holdings = 13F, 13D/G, OWN; meetings = proxies, AGM, CGR; calls = EC, PRES). Both page with `page` / `page_size` (default 25, max 100); `next_page` is null on the last page. Read any document whole with `get_document_text`; use `get_event_text` for one 8-K item, `get_filing_sections` for parsed sections, and the accession or reference in citations.", "paths": [ "/api/v1/filings", "/api/v1/companies/{id}/filings" ] }, { "name": "get_filing_sections", "title": "Parsed filing sections index", "description": "The text sections parsed out of a company's filings, newest filing first, each with a numeric section id, its type, label, title and word count, grouped by filing with the filing's accession number or document reference. SEC filers: 10-K / 10-Q items (item_1 business, item_1a risk factors, item_7 MD&A, item_9a controls, …) and proxy sections (proxy_cdna, proxy_governance, …). Exchange issuers (XDFM000001 Emaar, XADS000024 Aldar, …): every note of the financial statements (fs_note) and the annual report's chapters (ir_*). Paged by filing: `limit` filings (default 10), `offset` = the previous next_offset; narrow with `document` (one filing's accession or reference), `types` (filing form codes) and `section_types`. The reply's `filing_types` and `section_types` count what the whole index holds, so a model can see what to ask for. Read a section with `get_section_text`. The index lists what has been parsed, not everything filed: a missing section type means not parsed, never 'not disclosed'. Cite the parent filing's form type and accession or reference.", "paths": [ "/api/v1/companies/{id}/filing-notes" ] }, { "name": "get_section_text", "title": "Filing section text", "description": "The plain text of one parsed filing section (MD&A, risk factors, a financial-statement note, an annual-report chapter). `section_id` is the numeric id from `get_filing_sections`. The response is the section text itself, not JSON, read in windows: up to `max_chars` characters (default 20,000) from `offset`; a long section ends with a line giving the next offset — call again with it until the line says the end. Quote sparingly and cite the parent filing's accession number or document reference.", "paths": [ "/api/v1/companies/{id}/filing-notes/{sectionId}" ] }, { "name": "get_events", "title": "8-K items and exchange disclosures", "description": "Material corporate events. With `id`: that company's 8-K items (item code, name, filing date, accession number) — or, for an exchange-listed issuer (XDFM000001 Emaar, XDFM000029 Salik, …), its exchange disclosures classified the same way (`accessionNumber` is then the document reference, e.g. DFM-EMAAR-20261013-DISC, and `document_kind` exchange_disclosure) — newest first, paged with `limit` / `offset` (`total`, `next_offset`). Company filters: `from` / `to` (filing date), `family` / `families` (keeps the items whose SEC item defines the family — 5.02 leadership, 2.02 earnings, 1.01 agreement, 2.01 mna, 5.07 governance_vote, … — or whose span-verified facts, get_event_facts, belong to it; dividend, buyback, guidance and other families without an item of their own match only extracted facts), `query` (case-insensitive, over the item names and the items' extracted facts: headline, summary, quote), `sort`. Without `id`: the market-wide event wire; `query` matches headlines, tickers and company names; `family` / `families`, `from` / `to`, `sort`, paged with `offset` / `next_offset`; `counts: true` adds per-family totals. Read one item's text with `get_event_text` (accession or document reference + item). Event families: dividend, stock_split, guidance, earnings, mna, debt_financing, equity_financing, buyback, restatement_non_reliance, cyber_incident, restructuring, impairment, leadership, governance_vote, agreement, legal_regulatory, listing_compliance, other.", "paths": [ "/api/v1/companies/{id}/events", "/api/v1/companies/{id}/observations", "/api/v1/events/wire" ] }, { "name": "get_event_text", "title": "8-K item or exchange disclosure text", "description": "The stored text of one 8-K item — or of one exchange disclosure that get_events lists (document reference such as DFM-EMAAR-20261013-DISC, with its item code) — as plain text, read in windows of `max_chars` (default 20,000) from `offset`; a long item ends with a line giving the next offset. `accession` comes from `get_events` (or `list_filings`). `item` is the item code such as 2.02; omit it and it is resolved from the filing's items, ignoring Item 9.01 (the exhibit list) when the filing has a substantive item — if several substantive items remain, the error lists them so you can pick. A document with no extracted item text is read whole with `get_document_text`. Cite as: 8-K (or the exchange disclosure), accession or document reference, item code.", "paths": [ "/api/v1/companies/{id}/events/{accession}" ] }, { "name": "list_transcripts", "title": "Earnings-call transcript index", "description": "The earnings-call transcripts on file for a company, newest first: transcript id, call date, fiscal quarter label and duration; `limit` (default 20) and `offset` page it (`total`, `next_offset`). Feed the id (and nothing else — the required date is resolved automatically) to `get_transcript`. Ids: ticker, CIK or platform key (XDFM000004 DIB).", "paths": [ "/api/v1/companies/{id}/transcripts" ] }, { "name": "get_transcript", "title": "Earnings-call transcript text", "description": "One earnings-call transcript as plain text, read in windows of `max_chars` (default 20,000 characters; a call runs to ~60,000) from `offset`: the reply ends with the source line and, until the end, the offset to read on from. With annotations=true, the span-anchored observations extracted from the call instead (guidance statements, metric mentions, sentiment, each tied to an exact quote) as JSON; a call not yet extracted says so. With timeline=true, when each speaker turn starts and ends in the call's recording (speaker, role, section, startSeconds, endSeconds, in call order); `turns` is empty when the call carries no timings. Omit `transcript_id` for the most recent call; the transcript date the API requires is resolved from the index automatically. Transcripts are primary-source quotes: attribute what you cite to the speaker and the call date.", "paths": [ "/api/v1/companies/{id}/transcripts", "/api/v1/companies/{id}/transcripts/{transcriptId}", "/api/v1/companies/{id}/transcripts/{transcriptId}/annotations", "/api/v1/companies/{id}/transcripts/{transcriptId}/timeline" ] }, { "name": "get_guidance", "title": "Management guidance from earnings calls: promises and scorecards", "description": "What management promised ON EARNINGS CALLS and whether they delivered, in one call: `promises` = the open commitments extracted from the latest earnings call (bucketed by horizon, each with speaker and exact quote), `scorecard` = how past numeric guidance resolved against reported results (hit rate, per-prediction guided range vs realized value). Only verified, per-call-audited guidance is served; when nothing is, `empty_reason` says why (no call held, no verified commitment, guidance tracked but not yet reconciled). Targets and outlooks printed in investor presentations are a different source: `deck_guidance` counts them, and get_presentations with view \"guidance\" reads them. Ids: ticker, CIK or platform key (XDFM000004 DIB). Attribute each promise to its speaker and call date; a guided range is a claim by management, not an Astreus estimate. Other `view`s: `company_breakdown` = the company's scorecard by executive (each speaker's hit rate and dated record) and by earnings call; `events` = scored earnings calls across companies, newest first (`id` = a ticker narrows it, `with_commitments` keeps calls with resolved guidance), `event` = one scored call's commitments (`event_id` from `events`); `executives` = the credibility leaderboard (guidance kept vs missed, per speaker), `executive` = one speaker's record (`executive` = the speaker_name as listed). The scored set runs behind the call calendar: `stalenessNote` says when the newest scored call is old.", "paths": [ "/api/v1/companies/{id}/earnings/promises", "/api/v1/companies/{id}/earnings/scorecard", "/api/v1/companies/{id}/presentation-guidance", "/api/v1/companies/{id}/scorecard", "/api/v1/scorecards/events", "/api/v1/scorecards/events/{id}", "/api/v1/scorecards/executives", "/api/v1/scorecards/executives/{name}" ] }, { "name": "get_news", "title": "Live news tape", "description": "The Astreus news tape, built from primary sources: SEC filings as they are accepted (8-K items, 13D/G, Form 4, …), issuer press releases, exchange and regulator notices, central-bank releases and licensed wires. Each item carries the SOURCE timestamp (publishedAt), when Astreus first saw it (observedAt), tickers, topic codes, an importance score, a storyline id (clusterId — items sharing one describe the same event) and the attribution line to show. With `company` (ticker, CIK or platform key): that issuer's tape, including its corporate predecessors. Otherwise the market-wide feed, narrowed by `tickers`, `topics` (e.g. EARNINGS, GUIDANCE, MNA, LEADERSHIP, HALT, MACRO_PRINT, CENTRAL_BANK, FDA), `query` (full text) and `flash_only`. Ordered by publishedAt, newest first (a story that reached Astreus late sits at its publication time); to read older items pass `before` = the previous response's nextCursor (null when there are none), and to poll for what is new pass `since_id` = the previous response's latestId. A market-wide `query` is a full-text search of the tape (newest first, paged the same way with `before`). Other views: `top` = the most important stories of a `window` (6h, 24h default, 7d), one per storyline; `story` = one item by `item_id` (an `id` from any list) with its entity tags (companies, people, indicators, each with how it was matched), the rest of its storyline (up to 10) and the full text only where the source's licence allows it (`body` null otherwise); `sources` = every source with its licence class, display policy, attribution line and 24-hour count; `topics` = the topic codes `topics` accepts, with 24-hour counts. Rules: attribute every headline to its source (`attribution`, `url`, `formType`) — it is the source's wording, not Astreus's; `snippet` is null where the license permits headline-only display, so never infer content beyond the headline; for the text of an 8-K item use `get_event_text`.", "paths": [ "/api/v1/companies/{id}/news", "/api/v1/news/feed", "/api/v1/news/search", "/api/v1/news/top", "/api/v1/news/items/{id}", "/api/v1/news/sources", "/api/v1/news/topics" ] }, { "name": "analyze_transcript_topics", "title": "Compare transcript topics and analyst Q&A", "description": "Company/topic matrix, topic evolution and current-versus-previous equal-day window counts using explicit lexical categories. Analyst turns and indexed exchanges are measured separately; a turn may contain several questions and topics overlap. Without a company filter (`company`, `companies` or `mentioned`) a window is at most 92 days and defaults to the 92 days ending `to`; with one it defaults to the latest twelve months. Coverage is explicit, and capped topics must not be used to infer trends. Use role analyst and section qa to inspect topics analysts raise. Country and region describe issuer metadata; city comes from the currently stored business address. Source evidence is retrieved with search_transcripts using the returned topic/company/period filters.", "paths": [ "/api/v1/transcripts/search/topics" ] }, { "name": "search_transcripts", "title": "Search earnings-call transcripts", "description": "Full-text search over every spoken word in the earnings-call and event transcripts Astreus holds (US large caps from 2020, Gulf issuers, conference talks). Websearch syntax: quoted phrases, OR, -exclusion. Each passage names the speaker and role, the company, the call (e.g. 'Q3 2026 earnings call') and the date, and carries charStart/charEnd — the exact span in the transcript that get_transcript returns — so a quote can be cited to the word. Newest first by default; `sort: relevance` ranks by match quality. Paged: 20 passages by default (max 50; with include_context 10), the next page with `cursor` = nextCursor; a page is capped at 60 KB. Pass `summary: true` for how often the term comes up per calendar quarter and which companies say it most. `view: \"geography\"` lists the values the geography filters take: without `country`, every country code and name; with `country` (ISO-2), the business-address cities of the companies holding a transcript there, with company counts (pass one as `city`). Theme expansion is explicit lexical matching, not semantic inference. Set include_context to inspect the surrounding speaker turns or Q&A exchange. Attribute every quote to the named speaker and call date; it is their wording.", "paths": [ "/api/v1/transcripts/search", "/api/v1/transcripts/search/summary", "/api/v1/transcripts/search/facets" ] }, { "name": "get_mentioned_by", "title": "Who is talking about a company", "description": "Every passage where OTHER companies name the given company on their own earnings calls and events — customers describing dependence, suppliers describing demand, competitors describing pressure — newest first, with the speaker, role, call and date, and the exact span (charStart/charEnd) in that company's transcript. Paged: 20 passages by default (max 50; with include_context 3, each carrying its Q&A exchange), the next page with `cursor` = nextCursor, at most 60 KB a page. Use query or theme to narrow to a topic within the same passage; use include_context for the indexed Q&A exchange or surrounding turns. The subject's own calls are excluded unless `include_self` is true. Pass `summary: true` for mentions per calendar quarter and the companies doing the talking (the trend Quartr-style 'mentioned by' shows). Coverage is bounded by the calls Astreus holds: absence means no held call names the company, not that nobody does.", "paths": [ "/api/v1/companies/{id}/mentioned-by", "/api/v1/companies/{id}/mentioned-by/summary" ] }, { "name": "get_supply_chain", "title": "Disclosed suppliers, customers and competitors", "description": "A company's suppliers, customers and competitors with the numbers their filings actually state (partners are not served: a partnership cannot be evidenced reliably). Every metric says WHOSE figure it is (`whose`), the measurement period, the disclosing filing (`provenance.accession`, `provenance.public_at`) and, when withheld, `reasons` — quote all of that with the number, and never present a percentage without naming whose revenue it is a share of (\"27.6% of Fabrinet FY2025 revenue\", not \"NVIDIA's exposure\"). `discloser_revenue_pct` is the discloser's share of its own revenue from that party; `attributed_revenue_amount` is that share × the same filing's revenue (approximate, with `low`/`high`); `receivables_pct` is a balance, not revenue. Anonymous counterparties (\"Customer One\") are filing-scoped and never the same entity across filings. `coverage` is the disclosed-customer share of the company's own revenue for one filing and period — disclosure coverage, never an estimate of the whole network — and `state=overlap_unknown` means the total is withheld. `status` distinguishes not_processed, no_disclosures_found, partial and ok, and `not_available` means no network is published for the company (not processed, or below the five-named-counterparty threshold); an empty list is not \"no relationships\". The drawing `graph` comes only with `include_graph`. `as_of` returns what was public through that UTC date under today's rules. Pass `edge_key` (from a list row) for the full history and evidence of one relationship; cite with get_fact_source using statement=supply_chain and the metric's `provenance.fact_source_key`.", "paths": [ "/api/v1/companies/{id}/supply-chain", "/api/v1/companies/{id}/supply-chain/{edgeKey}" ] }, { "name": "get_company_debt", "title": "Company debt disclosures", "description": "One company's debt as it disclosed it, from its financial statements' borrowings notes and its issuance documents: each bond, note, sukuk and capital instrument (terms such as coupon, maturity, issue date, ISIN, issue and carrying amounts, each with its basis and source_id), the credit facilities, the snapshot's totals and its filed maturity ladder, with `coverage` (complete / partial / unavailable) and `coverage_note` saying what the record includes. Pass `instrument_id` (from `instruments`) for one instrument's every disclosure, or `source_id` (from any term) for that source's document, page and excerpt. `unavailable` means the company's debt has not been read yet, not that it has none: the reply then lists the companies that are covered. Ids: ticker, CIK or platform key (XDFM000001 Emaar, XDFM000003 Emirates NBD). Use `screen_corporate_bonds` to compare instruments across issuers and `get_note_tables` (family DEBT_SCHEDULE) for the printed borrowings tables. Source-backed issuer disclosures; partial pilot coverage, not a market price feed (no prices, yields or ratings). Cite each value's document_ref, observation_date, amount basis, currency and source_id. Carrying amounts and original issuance amounts are distinct. Null is not zero. Prior disclosures do not establish current outstanding status. Equity-classified Tier 1 instruments are separately labelled and excluded from debt totals. as_of uses publication time under current eligibility rules.", "paths": [ "/api/v1/companies/{id}/debt", "/api/v1/companies/{id}/debt/{instrumentId}", "/api/v1/companies/{id}/debt/sources/{sourceId}", "/api/v1/debt/instruments" ] }, { "name": "screen_corporate_bonds", "title": "Corporate bond disclosure screener", "description": "Every individual bond, note, sukuk and capital instrument across the covered issuers (Gulf banks and developers, US large caps; a partial pilot), filtered by currency, kind, words and an as-of date, sorted by maturity, coupon, amount or issuer, 20 per page by default (next page: `cursor` = page_info.next_cursor). Each row carries its terms with source_ids, its status and the documents that disclosed it; the sources come back as one line per document (`include_sources: true` adds the clipped excerpts). `company` keeps one issuer (CIK or platform key, e.g. XDFM000003 Emirates NBD); `covered_companies` lists every covered issuer with its instrument count. Borrowing groups and programme aggregates appear only with `kind: group`; matured, repaid and redeemed instruments only with `include_matured: true`. `view: \"issuers\"` groups the same filters by reporting company instead (one row per issuer: instrument count, next and final maturity, coupon range, currencies, kinds; largest market cap first; sort market_cap, bonds, issuer, maturity or coupon; not paged). `instrument_id` (from any row) reads one instrument without its company: its current record and every filing that disclosed it, with `as_of` and `include_sources`. Use `get_company_debt` for one company's totals, facilities and maturity ladder, and for one source's detail. Source-backed issuer disclosures; partial pilot coverage, not a market price feed (no prices, yields or ratings). Cite each value's document_ref, observation_date, amount basis, currency and source_id. Carrying amounts and original issuance amounts are distinct. Null is not zero. Prior disclosures do not establish current outstanding status. Equity-classified Tier 1 instruments are separately labelled and excluded from debt totals. as_of uses publication time under current eligibility rules.", "paths": [ "/api/v1/debt/instruments", "/api/v1/debt/issuers", "/api/v1/debt/instruments/{instrumentId}" ] }, { "name": "get_calendar", "title": "Calendar: earnings, economic releases, corporate events, Congress, a company's dated events", "description": "What is scheduled between two dates, from one of four feeds (`kind`): `earnings` (results dates and calls worldwide, confirmed or estimated; `live_only` = calls streaming now), `economic` (US statistical releases and FOMC decisions, with the headline print once released), `corporate` (shareholder meetings, leadership changes, dividends by declared/record/pay date, capital actions, listings), `congressional` (US House and Senate committee hearings and markups, plus each chamber's session days). Two more kinds need no dates: `company` (with `company`: that issuer's own dated disclosure events, newest first: 8-K items on their event date, earnings releases, dividend declarations and ex-dates, leadership changes, annual meetings, each with its item code and accession; `fiscalYearEnd`; paged with `limit` / `offset` (route default 100), optional `from` / `to` and `earnings: true` for results releases only) and `earnings_coverage` (how far the earnings calendar covers each company: readiness, monitoring state, the next date, and how many upcoming periods the issuer scheduled versus Astreus estimated; narrow with `company`, `country`, `query`; paged). Use it for what is coming or what happened on given days; use `get_events` for a company's filed 8-K history and `get_calendar_event` for one event's detail (date revisions, past calls, the next scheduled releases). Defaults to the next 7 days (with `company`: the next 120); a window is at most 93 days (economic: 400). Paged: pass `offset` = the previous `next_offset`. An economic print from a third-party publisher (Moody's, Coinbase, …) is withheld (`headlineWithheld`) — say so rather than looking for it elsewhere. Every row carries its evidence (docRef/accession, sourceUrl or the publisher's link): cite it. A missing date, time or print means not announced or withheld, never zero. Dates are the issuer's or publisher's local day; `time` comes with its `timezone`. This is a schedule, not advice.", "paths": [ "/api/v1/earnings/calendar", "/api/v1/earnings/live", "/api/v1/economic/calendar", "/api/v1/corporate/calendar", "/api/v1/congressional/calendar", "/api/v1/companies/{id}", "/api/v1/companies/{id}/calendar", "/api/v1/earnings/coverage" ] }, { "name": "get_calendar_event", "title": "One calendar event's detail", "description": "One event from `get_calendar`, by its `kind` and `id`: an earnings date's revision history (each change of date, status or evidence, newest first; routine re-saves of an unchanged estimate are folded into the revision they repeat, counted in `repeated`), the company's past results dates and, once reported, the headline results with their filing; an economic release's series and its next scheduled dates; a congressional meeting's committees, witnesses and link. Corporate events have no detail record: their `get_calendar` row already carries every date and the source filing (read the filing with `get_event_text`). Every row carries its evidence (docRef/accession, sourceUrl or the publisher's link): cite it. A missing date, time or print means not announced or withheld, never zero. Dates are the issuer's or publisher's local day; `time` comes with its `timezone`. This is a schedule, not advice.", "paths": [ "/api/v1/earnings/calendar/{id}", "/api/v1/economic/calendar/{id}", "/api/v1/congressional/calendar/{id}" ] }, { "name": "get_country", "title": "Country profile and map", "description": "Start here for any country. Returns its profile (name, capital, system of government, key facts; on request headline indicators, yield and money-market curves, leaders, first-level regions) and `branches`: the country page's tabs and the sub-tabs it fills, each with the tool and argument that reads it — economy → `get_economy(section)` (growth_activity, labour_market, inflation_prices, …, with how many series and which questions each holds), central_bank → `get_central_bank(section)`, government → `get_government(section)` (each section also names the `view` calls that read its parts in full), and where released military → `get_military(section)` and foreign_relations → `get_foreign_relations(section)`. Walk the tree: read one sub-tab at a time, then `get_macro_series` for one series' full history. Headline: `gdpGrowth` is REAL GDP growth and `inflation` CPI inflation, both % year on year, from the same series `list_countries` reads; `headlinePeriods` gives each figure's period and `headlineNotes` what it measures. A null headline field means not held, never zero. Cite each figure with the series title, its period and the `source` (publisher and link). A missing period or a null is not zero. Read `unit` before scaling (Percent, Millions of AED, Index 2015=100, …). Data, not advice.", "paths": [ "/api/v1/countries/{iso}", "/api/v1/countries/{iso}/regions" ] }, { "name": "get_economy", "title": "A country's economy, one sub-tab at a time", "description": "One sub-tab of a country's Economy, exactly as the country page draws it: `section` growth_activity, labour_market, inflation_prices, consumption_households, housing_real_estate, credit_funding, trade_external, fx, energy, tourism_transport (countries that publish it, e.g. AE), industry_technology or fiscal. Returns the sub-tab's headline cards, then its questions (`modules`, e.g. \"How fast is the economy growing?\") each with headline cards, the charts it draws (series ids) and its table, then the sub-tab's other series (paged: `offset` = the previous `next_offset`). Each card: `id` (for get_macro_series), label, unit, latest value and period, the prior print, the print a year earlier and `change_1y` (% for levels, points for rates; `shown_as` says when the page reads a series as its year-on-year change, e.g. a price index as inflation). Without `section`: the sub-tabs the country fills, with their series counts and questions. Latest prints only; `get_macro_series` reads a full history. Values are the CURRENT vintage: the latest published figure for each period, revisions included. Do not present one as what was known at the time; say it is the current estimate. Cite each figure with the series title, its period and the `source` (publisher and link). A missing period or a null is not zero. Read `unit` before scaling (Percent, Millions of AED, Index 2015=100, …). Data, not advice.", "paths": [ "/api/v1/countries/{iso}" ] }, { "name": "get_central_bank", "title": "A country's central bank, one sub-tab at a time", "description": "One sub-tab of a country's central bank (the Federal Reserve for US, the Central Bank of the UAE for AE), as the country page draws it. `section`: overview (the policy rate and the overview's questions — money, balance sheet, reserves, liquidity, rates, credit — with their cards), statistics (AE: the bank's other statistical series, paged), financials (AE: balance-sheet lines from the Statistical Bulletin; US: the Reserve Banks' combined statements, newest years — `get_central_bank_financials` reads every Bank, period and note), commentary (AE: base-rate decisions, press releases, public statements, financial-stability, periodic and annual reports, research), fomc (US: statements, press conferences, minutes), beige_book (US) or speeches (US). Document sections (commentary, fomc, beige_book, speeches) list the newest documents of each of their groups (`limit` each, default 5, with each group's `total`); pass `group` (e.g. press-releases, minutes) to page one group (`limit` default 20, `offset` = its `next_offset`). Read one with `get_policy_document`; search their text with `search_policy_text` (same `group` names). `get_country` lists which sections a country has. Three reads of the bank's text beside the sub-tabs: text_overview (US, AE: how many documents of each type are held and analysed, from when, the newest release of each type and what the bank has been discussing), beige_book_districts (US: each Reserve Bank district's net direction and net sentiment per Beige Book release, newest first; `limit` releases, default 8, max 24) and forward_guidance (US: the forward-looking policy language in the newest statements, minutes and press conferences — what the bank signalled about rates — each with its quote, `observation_id` and document; `limit` default 8, max 50; pass `observation_id` to get the sentence before and after one quote, cut from its document). Cite each figure with the series title, its period and the `source` (publisher and link). A missing period or a null is not zero. Read `unit` before scaling (Percent, Millions of AED, Index 2015=100, …). Data, not advice.", "paths": [ "/api/v1/countries/{iso}", "/api/v1/countries/{iso}/policy-text/documents", "/api/v1/countries/{iso}/fed-financials", "/api/v1/countries/{iso}/policy-text", "/api/v1/countries/{iso}/policy-text/districts", "/api/v1/countries/{iso}/policy-text/guidance", "/api/v1/intelligence/observations/{id}/context" ] }, { "name": "list_macro_series", "title": "Macro series catalog", "description": "The macro series Astreus holds for a country (ISO-2, e.g. AE), one of its regions (ISO 3166-2, e.g. AE-DU for Dubai) or a government entity (its code, e.g. AE.DU.RTA), filtered by words in the title, key or publisher, by the country page's Economy sub-tab (`section`, the slugs get_economy takes: labour_market, inflation_prices, …) or by the cube's `category` (labor, prices, …: a different, coarser taxonomy). Each row has the `id` that `get_macro_series` reads, its unit, frequency, latest value and period and its publisher. Use it when `search` does not find a series, or to see everything a country publishes on a topic (e.g. geo AE, query \"eibor\"); `get_economy` shows how the page composes a sub-tab. `categories` counts what exists before the text and category filters. Paged: `offset` = the previous `next_offset`. Cite each figure with the series title, its period and the `source` (publisher and link). A missing period or a null is not zero. Read `unit` before scaling (Percent, Millions of AED, Index 2015=100, …). Data, not advice.", "paths": [ "/api/v1/countries/{iso}", "/api/v1/countries/{iso}/regions", "/api/v1/countries/{iso}/government/entities/{code}/series" ] }, { "name": "get_macro_series", "title": "Macro series observations", "description": "One macro series' observations with its title, unit, frequency, seasonal adjustment and publisher. Pass `series` as returned by `search` or `list_macro_series`: `AE:EIBOR_3M`, `US:UNEMPLOYMENT_RATE`, `AE-DU:POPULATION` (a region) or `macro:20335` (a government entity's series). The older `iso` + `key` form still works. By default the latest 500 observations; bound them with `from` / `to` (YYYY-MM-DD) and `limit`; `window.olderTo` is the `to` that reads the observations before. An id that names no series is an error; to find series use `get_economy` (a country's sub-tabs) or `list_macro_series` (search a catalog). Values are the CURRENT vintage: the latest published figure for each period, revisions included. Do not present one as what was known at the time; say it is the current estimate. Cite each figure with the series title, its period and the `source` (publisher and link). A missing period or a null is not zero. Read `unit` before scaling (Percent, Millions of AED, Index 2015=100, …). Data, not advice.", "paths": [ "/api/v1/countries/{iso}/series", "/api/v1/macro/series/{seriesId}", "/api/v1/countries/{iso}" ] }, { "name": "search_policy_text", "title": "Search central-bank documents", "description": "Find central-bank documents by what they say: the Federal Reserve's FOMC statements, minutes and press conferences, speeches and Beige Books (from 1993; `country` US), and the Central Bank of the UAE's base-rate decisions, press releases, public statements, financial-stability, periodic and annual reports and research papers (from 2000; `country` AE). `query` searches each document's full text, title and speaker line: every word must appear; put a phrase in double quotes to keep it together (\"neutral rate\"). Each hit carries up to three passages around the match. A text search reads the newest documents that pass the other filters, a budget at a time, and `searched` says exactly which span it covered: when `next_offset` is set, older documents were NOT searched yet — pass it as `offset` to continue, or narrow with `group`, `doc_type` or `year` to cover a set in one call. Without `query`: the documents that pass the filters, newest first, with facets (years, speakers, districts). Filter by `group` (the same groups `get_central_bank` lists, e.g. minutes, speeches, press-releases), `doc_type`, `speaker` (words of the name: \"powell\"), Beige Book `district`, `year`. Read one with `get_policy_document`. Quote documents as the institution's own words, with the title and date. Not advice.", "paths": [ "/api/v1/countries/{iso}/policy-text/documents" ] }, { "name": "get_policy_document", "title": "Read a central-bank document", "description": "The text of one central-bank document found with `search_policy_text`, verbatim, in pages of up to `max_chars` characters (default 20,000): pass `offset` = the previous `next_offset` to read on. The header names the title, date, type, speaker and the institution's own link. Quote it as the institution's words, with the title and date. Not advice.", "paths": [ "/api/v1/countries/{iso}/policy-text/documents/{documentId}" ] }, { "name": "get_management", "title": "Officers, directors, leadership changes and shareholder votes", "description": "Who runs a company: its current officers (with the standard C-suite seat their title holds) and directors, from SEC Section 16 filings or, for Gulf issuers, the governance report and exchange disclosures; each with shares held as last reported and the latest director-election support. Also, on request, leadership changes from 8-K Item 5.02 (appointed, resigned, retired…, each with the filing's own sentence), shareholder-meeting vote results from 8-K Item 5.07 (per proposal and per nominee), and for non-US issuers the governance report's header facts (auditor, fees, board size) and related parties. Use it for 'who is the CFO', 'who sits on the board', 'what did shareholders vote'. Use `get_ownership` for insider trades and holdings over time. `include_former` adds people no longer in post. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/management" ] }, { "name": "get_ownership", "title": "Insider and institutional ownership", "description": "Who owns a company and how that changed, by `view`: `summary` = current insider positions (direct and indirect shares, from the latest Form 3/4/5), the largest institutional holders (13F, with the report period and accession) and recent Form 144 notices of proposed insider sales; `insider_transactions` = Form 4 trades, newest first, filterable by type (Sales, Purchases, Awards), date range and insider CIK, paged; `insider_history` = each current insider's position over time (every served snapshot, restated on today's share basis after splits), best for one insider (`owner`); `nationality_history` = foreign-ownership level against the permitted limit over time (Gulf-listed issuers). Use `get_management` for roles and board seats. Shares are counts; `value_usd` is the 13F filer's own reported value. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/ownership", "/api/v1/companies/{id}/ownership/transactions", "/api/v1/companies/{id}/ownership/insider-history", "/api/v1/companies/{id}/ownership/nationality-history" ] }, { "name": "get_dividends", "title": "Declared dividends", "description": "A company's dividends as it declared them: amount per share in its own currency (as declared, not split-adjusted), kind (final, interim, special), declared, record, last-entitlement, ex and payment dates, and the proof — the exchange notice or SEC filing (doc_ref, page, the figure as printed). `announced` = declared but not yet ex; `undated` = approved with no ex-date on record. Only the company's own disclosures are served: payments known only from market-data vendors are left out (`omitted_vendor_rows` counts them), so an early or missing year means not disclosed here, not unpaid. No yields are given. Use `get_calendar` (kind corporate, kinds dividend) for upcoming dividend dates across companies. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/dividends" ] }, { "name": "get_monthly_revenue", "title": "Monthly revenue (Taiwan)", "description": "The monthly revenue a regulator requires the company to publish — today Taiwan-listed issuers (TWSE/TPEx, about ten days after each month end) — with the year-over-year change and the filer's own note for the month. Values are in currency units as filed (thousands already expanded), current vintage. Most markets have no monthly mandate: a 'no series' answer means none is published, not zero. The series belongs to the Taiwan listing (platform key XTAI…), not a US ADR: given an ADR such as TSM the tool follows the company's Taiwan (MOPS) record from get_company's accounting_bases and says which record it read. Use `get_financials` for quarterly and annual statements. The result carries the Open Government Data License attribution: repeat `attribution` whenever you show these figures. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/monthly-revenue", "/api/v1/companies/{id}" ] }, { "name": "get_note_tables", "title": "Tables in the notes to the financial statements", "description": "The tables printed in a company's filing notes (inventory composition, debt schedules, PP&E by class, leases, tax, segment notes, …) and in its investor presentations, each served only after validation gates, with every cell traceable to the filing. By `view`: `index` = without `family` or `document`, one line per table family with its table count and period range (first page only) plus the documents, newest first, paged with `limit` / `offset`; with `family` (e.g. INVENTORY_COMPOSITION) or `document` (doc_ref) the tables themselves, paged; `table` = one table's grid as filed (`table_id` from the index); `series` = one notes family's lines over time across every filing (`family`, `cadence`), each point naming the document it came from and flagged when a later filing restated it — series are built from the notes only, so a deck family (kind presentations or guidance, lower-case keys) is read table by table instead. `kind` picks notes (default), presentations (deck tables) or guidance (deck tables of targets and outlooks; the guidance figures themselves, one row per target, are `get_presentations` view=guidance). Use `get_financials` for the face statements and `get_section_text` for narrative notes. Ids: ticker, CIK or platform key (XDFM000001 Emaar, XDFM000004 DIB). Values are in units of `currency` (already scaled; `scale` is the print's display scale), per-share and percent lines as printed. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/filing-notes/tables", "/api/v1/companies/{id}/filing-notes/tables/{tableId}", "/api/v1/companies/{id}/filing-notes/series" ] }, { "name": "get_financials_as_filed", "title": "Financial statements as originally filed", "description": "A company's statements exactly as printed in its filings, not standardized: every caption the company used (a renamed line is a new row), one column per period, values as filed. `view=grid` (default): `vintage` original (default) = what the company FIRST filed for each period, before any restatement — use it for 'what did they report at the time'; latest = the latest filing's figure; statements: income_statement, comprehensive_income, balance_sheet, balance_sheet_parenthetical, cash_flow_statement, equity. By default the latest 5 periods; window with `from` / `to` / `limit`. `view=printed`: the document that won a period and its printed table verbatim (`period` + `periodicity`): `raw` cells are the printed strings, in the print's `scale`; without `period`, the periods available. Use `get_financials` for comparable standardized lines and `get_fact_source` to trace one. Values are in units of the reporting currency (already scaled out of thousands/millions); rows flagged per_share_or_ratio are per share or ratios. Each column names its doc_ref; a cell from another filing names its own. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/financials/as-filed", "/api/v1/companies/{id}/financials/as-reported" ] }, { "name": "get_presentations", "title": "Investor presentations and the guidance printed in them", "description": "A company's investor presentations (results decks, roadshow and investor-day decks), by `view`: `decks` = the list, newest first by filing date (a deck the IR site left undated is placed at its fiscal period's end, `date_basis: period_end`; decks with no date at all come last), with doc_ref, title, the fiscal period covered and page count; a deck held twice (the IR-site PDF and the exchange's copy, or two identical attachments) is listed once, its other copies in `also_held_as` (`include_duplicates: true` lists every copy). To read one deck slide by slide, call `get_document_text` with the row's `document` (+ `part` for an SEC exhibit deck) and `page_from` = `page_to` = the slide number; its tables are `get_note_tables` with `document` = the doc_ref. `guidance` = the targets, outlooks and medium-term ambitions the company printed in those decks, one row per disclosure (the same target repeated in a later deck is a new row, so revisions show), each with the deck (doc_ref) and page, the figure as printed and the period it targets; newest deck first by default (`sort`: newest, target = latest target period first, key = grouped by guidance key); the reply's `keys` field lists every guidance key with its count, to filter with `key`. Use `get_guidance` for guidance spoken on earnings calls and how it resolved. Ids: ticker, CIK or platform key (XDFM000001 Emaar, XDFM000004 DIB). A target is the company's claim, not an Astreus estimate. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/presentations", "/api/v1/companies/{id}/presentation-guidance" ] }, { "name": "get_earnings", "title": "Earnings: reported quarters and what management said", "description": "A company's earnings, by `view`: `overview` = revenue and diluted EPS per reported quarter, oldest to newest, under the company's own accounting basis (`accounting_basis`: US GAAP, IFRS (IASB), …; a fourth quarter computed as full year minus nine months is flagged `revenue_derived` / `eps_derived`), the latest results release as filed (8-K Item 2.02 or the exchange release: revenue, gross profit, operating income, net income, EPS, with accession and acceptance time) and highlights from the latest earnings call, each with the speaker's exact quote (a null release or empty highlights carries `latest_release_note` / `highlights_note` saying why); `company` = id, name and ticker; `statements` = every verified statement the company's speakers made on calls, by `type` — causal_claim (X drove Y), guidance, metric, event, state — newest call first, searchable with `query` and limited to one call with `document_id` (from `calls`). Use `get_guidance` for open promises and how past guidance resolved, `search_transcripts` for full-text search across companies, and `get_transcript` for a whole call. Quote a statement as the speaker's words, with the call date; figures from releases cite the accession. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/earnings/overview", "/api/v1/companies/{id}/earnings/statements" ] }, { "name": "get_event_facts", "title": "Facts extracted from a company's 8-K filings and exchange disclosures", "description": "Structured facts read from a company's SEC 8-K items or, for an exchange-listed issuer (XDFM000001 Emaar, XDFM000029 Salik, …), its exchange disclosures, newest filing first: acquisitions and their deal value and counterparty, financings, buybacks, dividends, leadership changes, votes, agreements, restructurings, legal and listing matters, each with the filing's own supporting sentence and the accession. Filter by `family`, filing date (`from` / `to`); paged. Use it for 'what deals has X announced and for how much'. An 8-K fact names its `accession` and `item`; an exchange disclosure has no 8-K item (`item` null, `document_kind: exchange_disclosure`, `doc_ref` the disclosure, `title` its heading). Use `get_events` for the plain 8-K item index and `get_event_text` for an 8-K item's full text; read an exchange disclosure whole with `get_document_text` (document = doc_ref). Only span-verified facts are served. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/observations" ] }, { "name": "get_government_exposure", "title": "Regulators, laws, regulation, government awards and central-bank documents", "description": "How government touches a company, by `view`: `regulators` = the bodies that regulate it (securities regulator, exchange, sector and licensing regulators), each with what it does to the company and the evidencing sentence; `laws` = the laws, decrees and resolutions that bear on it, read at article level (Dubai and other non-US jurisdictions today): without `law_id` the list with each instrument's basis and effects, with `law_id` that instrument's articles quoted with their effect and an explanation; `us_regulation` = US legislation and executive actions linked to the company (it names the company, the company's filing cites it, or it acts on its industry) plus court cases and the legal-proceedings sections of its filings, with `coverage` (how much of the record has been read: a short list is not 'no exposure'); `federal_awards` = US federal contracts and grants (USAspending) to the company's mapped recipients: totals, by agency, and the largest awards; `central_bank` = Central Bank of the UAE documents that bear on the company (press releases, Base Rate decisions, public statements), newest first, each with the rule that tagged it (`basis` named = the text names the company, with the sentence; sector = it addresses the class of institution the company is licensed as) and what it does; read a document with `get_policy_document` (country AE, its document_id). Use `get_event_facts` for legal matters the company disclosed in 8-Ks. Quote laws as their own text with the instrument's title and number; a machine translation is flagged. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/regulators", "/api/v1/companies/{id}/laws", "/api/v1/companies/{id}/regulation", "/api/v1/companies/{id}/government-awards", "/api/v1/companies/{id}/central-bank" ] }, { "name": "get_market_events", "title": "Market events that bear on a company", "description": "Dated events relevant to a company's history, for reading its figures against what happened: global shocks (crashes, financial crises, pandemics, wars), its region's, country's and exchange's events, recessions of one `economy`, commodity shocks, and the company's own milestones, each with its date or span, precision (day, month or year), category, sentiment and sources. `matched_kind` says why the event applies (global, region, country, exchange, sector, commodity, company). Newest first by start date (`order: asc` for oldest first, the chart order). Ramadan periods (category calendar) are left out unless asked for. Ids: ticker, CIK or platform key (XDFM000001 Emaar). Use it to place a quarter in context; use `get_event_facts` for the company's own 8-K disclosures and `get_news` for headlines. Events are curated by Astreus from the cited sources. Cite each figure with its document (accession or doc_ref, and page where given) and its period or date. A null or absent value means withheld or never reported — say 'not available', never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/market-events" ] }, { "name": "get_market_board", "title": "Market board: commodities or currencies today", "description": "Today's cross-section of one market: `asset_class` commodities = every instrument of a `class` (energy: crude, products, gas, coal from EIA, World Bank, PPAC and Alberta; metals and agriculture: World Bank monthly Pink Sheet; compute: GPU-hour rental list prices by venue and the venue median) with its last price and date, previous print, 1M / YTD / 1Y returns, 52-week range and staleness; `asset_class` fx = every currency against `base` (default USD) with its rate and the base's return at 1D … 10Y. Use it for \"what moved\", \"which is cheapest\" or a current price; use `get_market_series` for one instrument's history or a pair's volatility and drawdown, and `get_commodity_analytics` for positioning, spreads and inventories. Commodity prices are spot or official reference prints (futures settlements are unlicensed); FX rates are daily blended central-bank reference rates (Frankfurter), not dealable quotes. Ornn OCPI GPU indices are withheld (licence). `get_macro_series` also holds some FRED copies of commodity and FX series (e.g. DCOILBRENTEU, DEXUSEU) and central-bank rates: use these market tools for commodity and currency prices, and get_macro_series for policy rates, interbank rates and other macro series. Cite each figure with its `source` (publisher and series) and date, and repeat any `attribution` line verbatim when you use the figure. A null or a missing date is not available, never zero; `stale` means the publisher has not printed within its usual interval. Read `unit` before comparing (USD per barrel, USD per metric ton, USD per GPU-hour, units of a currency per 1 base …); returns and volatility are decimals (0.05 = 5%; boards round them to 1e-6). Data, not investment advice: do not recommend buying, selling or holding.", "paths": [ "/api/v1/commodities", "/api/v1/fx" ] }, { "name": "get_market_series", "title": "Market series: one commodity's or currency pair's history", "description": "One instrument's daily (or monthly, for the World Bank Pink Sheet) price history. `asset_class` commodities: `id` is the board symbol (BRENT, WTI, HENRY_HUB, GOLD, COPPER, WHEAT, a GPU venue listing …, as `get_market_board` or `search` returns it); by default the result adds the instrument's reference sheet (`spec`: for a GPU its chip specification, the cloud operators that carry it and each venue's list price; exchange-listed contracts on it; pass include_spec=false to leave it out). An Ornn OCPI index (e.g. H100, the GPU's reference print) has no history here (licence) but still returns its spec sheet and venues. `asset_class` fx: `id` is a pair in either order (EURUSD, USDAED, USD/SAR): closes are units of the quote per 1 base, and by default the result adds the pair's statistics (1D … 10Y returns, 52-week and all-time range, one-year volatility and maximum drawdown, a peg flag, calendar-year returns, redenominations). By default the last year, at most 400 points; bound it with `from` / `to` (YYYY-MM-DD) and `limit` (max 2500); for decades of history pass `frequency` weekly or monthly (each week's or month's last close). Newest points are kept when `limit` cuts; `older.to` (= window.olderTo) is the `to` that reads the points before. Use `get_market_board` for many instruments at once. `get_macro_series` also holds some FRED copies of commodity and FX series (e.g. DCOILBRENTEU, DEXUSEU) and central-bank rates: use these market tools for commodity and currency prices, and get_macro_series for policy rates, interbank rates and other macro series. Cite each figure with its `source` (publisher and series) and date, and repeat any `attribution` line verbatim when you use the figure. A null or a missing date is not available, never zero; `stale` means the publisher has not printed within its usual interval. Read `unit` before comparing (USD per barrel, USD per metric ton, USD per GPU-hour, units of a currency per 1 base …); returns and volatility are decimals (0.05 = 5%; boards round them to 1e-6). Data, not investment advice: do not recommend buying, selling or holding.", "paths": [ "/api/v1/commodities/{symbol}/prices", "/api/v1/commodities/{symbol}", "/api/v1/fx/pairs/{pair}", "/api/v1/fx/pairs/{pair}/prices" ] }, { "name": "get_commodity_analytics", "title": "Commodity analytics: positioning, spreads, inventories, market map, GPU mentions", "description": "The derived commodity views, one `view` per call. `positioning`: CFTC Commitments of Traders for the futures markets of a class (managed-money long, short, net, week-on-week change, net as a share of open interest, producer and swap-dealer nets, as of the report's Tuesday); `id` (WTI, or a CFTC code) adds the weekly net history. `spreads`: spreads and ratios computed from their legs (Brent–WTI, 3-2-1 crack, TTF–Henry Hub, gold/silver …) with last, previous and 52-week range; `id` (e.g. BRENT_WTI) adds its history, bounded by `from` / `to` / `limit` (default the last year). `fundamentals`: US EIA weekly inventories and production with the change on the week and on the year and the gap to the five-year average (energy only); each row's `series` reads its history with `get_macro_series`. `market_map`: the sector tree with each benchmark's location, quality, unit, quoting convention, futures venue and which free source Astreus carries. `mentions`: what companies said about one GPU on their earnings calls (`id` = the GPU symbol, e.g. H100, B200, MI300X; newest first, at most 10 quotes, each with company, call, speaker, role, sentiment and date); mentions are tracked for GPU instruments only, and any other symbol answers tracked=false. Use `get_market_board` for prices and `get_market_series` for one instrument's history. Futures curves are not held (licence). Cite each figure with its `source` (publisher and series) and date, and repeat any `attribution` line verbatim when you use the figure. A null or a missing date is not available, never zero; `stale` means the publisher has not printed within its usual interval. Read `unit` before comparing (USD per barrel, USD per metric ton, USD per GPU-hour, units of a currency per 1 base …); returns and volatility are decimals (0.05 = 5%; boards round them to 1e-6). Data, not investment advice: do not recommend buying, selling or holding.", "paths": [ "/api/v1/commodities/positioning", "/api/v1/commodities/spreads", "/api/v1/commodities/fundamentals", "/api/v1/commodities/market-map", "/api/v1/commodities/{symbol}/mentions" ] }, { "name": "list_themes", "title": "Market themes: what managements are talking about", "description": "The market-themes catalog: recurring themes in what company managements say on their earnings calls (e.g. 'regional supply-chain disruption affecting project execution'), each with its breadth (distinct companies raising it), momentum (memberships in the last half-year minus the half-year before), lifecycle (emerging, accelerating, steady, fading, dormant), tone (`net_direction`, −1..1) and the companies behind it. Use it for 'what is the market talking about' or 'which themes are gaining breadth'; use `get_theme` for one theme's companies and quotes, `get_company_themes` for the themes one company is part of, `get_topic_trends` for a fixed topic's quarterly counts since 2020, `analyze_transcript_topics` / `search_transcripts` for word counts and passages over all transcripts. Filters: `query` (words in the name or description), `countries` (issuer domiciles), `sector`, `scope` (market = many companies, regional = one country or the GCC, company = one company's own theme), `lifecycle`. Dormant themes (no membership for a year) are left out unless `include_dormant`. The first page carries `coverage` (which issuer countries the catalog holds): a company or country outside it has no themes here. Paged: `offset` = the previous `next_offset`. `view: \"pulse\"` = what changed this week instead: lifecycle transitions, breadth spikes and momentum movers, ranked, each with its strongest quote; narrow it with `tickers` (themes those companies raised) or `sector`. The pulse ranks the theme registry; while a management-commentary release serves the catalog the pulse is empty and `empty_reason` says so (browse the catalog instead). Quotes are the speaker's own words: quote them verbatim, naming the speaker, the company, the call (`call`) and its `date`; `transcript_id` and `span` locate the passage for get_transcript. Counts are over the calls Astreus holds: a company or theme that is absent was not found there, which is not zero activity elsewhere. Breadth and momentum describe how many companies raise a theme, not whether it is true. Data, not advice.", "paths": [ "/api/v1/intelligence/narratives", "/api/v1/intelligence/narratives/facets", "/api/v1/intelligence/pulse" ] }, { "name": "get_theme", "title": "One market theme: its companies and what they said", "description": "One theme from `list_themes` or `get_company_themes`, by `id`: its definition (what counts and what does not), breadth, lifecycle and tone, the quarterly series (memberships, cumulative companies, tone), the sectors it spread through, and its member companies — each with when it joined, how often and in which direction it raised the theme, whether it leans against the consensus (`divergent`), and its newest quotes with speaker, call, date and transcript span. Members are paged (`members_offset` = the previous `members_next_offset`), most memberships first by default; `company` returns only that company's membership and quotes. Use `search_transcripts` to find wording beyond these quotes and `get_transcript` to read the surrounding call. Quotes are the speaker's own words: quote them verbatim, naming the speaker, the company, the call (`call`) and its `date`; `transcript_id` and `span` locate the passage for get_transcript. Counts are over the calls Astreus holds: a company or theme that is absent was not found there, which is not zero activity elsewhere. Breadth and momentum describe how many companies raise a theme, not whether it is true. Data, not advice.", "paths": [ "/api/v1/intelligence/narratives/{id}", "/api/v1/companies/{id}" ] }, { "name": "get_company_themes", "title": "The themes one company is part of", "description": "Every market theme a company's management has raised on its earnings calls: for each, the theme's breadth, lifecycle and consensus tone, and the company's own participation (how many times and on how many calls, when it joined and last raised it, its direction and whether it leans against the consensus), the peers in the same theme, and the company's newest quote with speaker, call, date and transcript span. Use it for 'which themes is X part of' or 'where does X disagree with its peers'; use `get_theme` for every member of one theme. Sorted by the company's own mentions (or `recent`, `breadth`); paged with `offset` = the previous `next_offset`. An empty list carries `coverage`: the catalog holds only the issuer countries listed there. Quotes are the speaker's own words: quote them verbatim, naming the speaker, the company, the call (`call`) and its `date`; `transcript_id` and `span` locate the passage for get_transcript. Counts are over the calls Astreus holds: a company or theme that is absent was not found there, which is not zero activity elsewhere. Breadth and momentum describe how many companies raise a theme, not whether it is true. Data, not advice.", "paths": [ "/api/v1/intelligence/company/{id}/themes", "/api/v1/intelligence/narratives/facets" ] }, { "name": "list_asset_companies", "title": "Which companies and layers have mapped physical assets", "description": "The directory of the physical-asset register: every company with reviewed, sourced assets on the map (with how many), the map layers and the asset kinds each holds (real estate, hospitality, retail, restaurants, fuel stations, toll gates, ports, airports, energy, data centres, …), and with `by_country` how many assets each country has per layer. Use it to find out whether a company or a kind of asset is covered before calling `get_company_assets` (one company) or `search_assets` (a country or area). A company absent here has no mapped assets yet, which does not mean it has none. Cite an asset's facts with the sources `get_asset` lists (publisher, link, excerpt) and carry the result's `attribution` lines (OpenStreetMap, Overture, Copernicus, … require them). An asset not listed, or a null field, means not mapped or not yet reviewed and sourced, never that it does not exist; a null `status` means no dated lifecycle event yet. `location` is the label point with its declared `precision` (exact, approximate, locality, region, country) and error radius `precision_m`; when it is null with `location_withheld` (odbl, share_alike, licence_unknown) the asset is mapped but its coordinates come from a share-alike dataset and are not passed on: say so, never estimate them. Data, not advice.", "paths": [ "/api/v1/geo/companies", "/api/v1/geo/layers", "/api/v1/geo/countries" ] }, { "name": "get_company_assets", "title": "A company's physical assets", "description": "A company's physical assets as of a date: `summary` counts (by kind, country, lifecycle status, and asset vs component) over every asset that passes the filters, then one page of them with name, kind, status and status date, operating-since date, attributes (floors, keys, GLA, units, … as the kind records them), the company's roles (owner, operator, developer, concessionaire, …), disclosed share and how it holds it (period, vehicle and stake), the geometry licence and the location when it may be passed on. `holding=former` lists the assets it held and no longer does; `consolidated` adds its listed subsidiaries' assets, each naming the subsidiary. Use `get_asset` for one asset's parties over time, lifecycle, sources and measured series; `search_assets` for assets of any company in a country or area. Paged: `offset` = the previous `next_offset`. Cite an asset's facts with the sources `get_asset` lists (publisher, link, excerpt) and carry the result's `attribution` lines (OpenStreetMap, Overture, Copernicus, … require them). An asset not listed, or a null field, means not mapped or not yet reviewed and sourced, never that it does not exist; a null `status` means no dated lifecycle event yet. `location` is the label point with its declared `precision` (exact, approximate, locality, region, country) and error radius `precision_m`; when it is null with `location_withheld` (odbl, share_alike, licence_unknown) the asset is mapped but its coordinates come from a share-alike dataset and are not passed on: say so, never estimate them. Data, not advice.", "paths": [ "/api/v1/companies/{id}/assets" ] }, { "name": "search_assets", "title": "Physical assets in a country or area", "description": "Mapped physical assets of every company in some countries or inside a bounding box, filtered by layer, kind, status and name: ports and terminals, airports, fuel stations, restaurants, malls, toll gates, energy assets, data centres, … Each row has the listed company that is its primary party today (`primary_party_cik`), when one is. `summary` counts the matching assets before paging. Use it for questions about a place or a kind of asset (\"ports in Oman\", \"data centres in Saudi Arabia\"); use `get_company_assets` for one company's register. Pass `countries` or `bbox`. `truncated` = the area holds more than 5,000 assets and the summary covers only the first: narrow it. Paged: `offset` = the previous `next_offset`. Cite an asset's facts with the sources `get_asset` lists (publisher, link, excerpt) and carry the result's `attribution` lines (OpenStreetMap, Overture, Copernicus, … require them). An asset not listed, or a null field, means not mapped or not yet reviewed and sourced, never that it does not exist; a null `status` means no dated lifecycle event yet. `location` is the label point with its declared `precision` (exact, approximate, locality, region, country) and error radius `precision_m`; when it is null with `location_withheld` (odbl, share_alike, licence_unknown) the asset is mapped but its coordinates come from a share-alike dataset and are not passed on: say so, never estimate them. Data, not advice.", "paths": [ "/api/v1/geo/features" ] }, { "name": "get_asset", "title": "One physical asset: parties, lifecycle, sources and measured series", "description": "Everything held on one physical asset, by the `key` that `get_company_assets` or `search_assets` returned: description and names, kind, attributes, every party with its role, share and validity period (and the vehicle it holds through), the dated lifecycle (announced, under construction, operating, …, each with its date precision and source), parent and components, links to other assets, external ids (OpenStreetMap, Wikidata, Overture), area or length, and the sources behind each fact (publisher, link, page, excerpt). With `include_data` (default true) it adds the asset's measured series with each point's source: construction progress from the Dubai Land Department registry and its projects, satellite built-up and change fractions (Sentinel-2, Landsat), disclosed and estimated data-centre power and capex, mall occupancy and footfall. Toll-gate traffic is not served here (its provider's terms forbid it). A series is what was measured over the last two years; a missing period is not zero. Cite an asset's facts with the sources `get_asset` lists (publisher, link, excerpt) and carry the result's `attribution` lines (OpenStreetMap, Overture, Copernicus, … require them). An asset not listed, or a null field, means not mapped or not yet reviewed and sourced, never that it does not exist; a null `status` means no dated lifecycle event yet. `location` is the label point with its declared `precision` (exact, approximate, locality, region, country) and error radius `precision_m`; when it is null with `location_withheld` (odbl, share_alike, licence_unknown) the asset is mapped but its coordinates come from a share-alike dataset and are not passed on: say so, never estimate them. Data, not advice.", "paths": [ "/api/v1/geo/features/{key}", "/api/v1/geo/features/{key}/data" ] }, { "name": "get_digital_assets", "title": "A company's digital assets: chips, apps, websites, cloud platforms", "description": "What a company owns that has no place on a map — chip designs (GPUs, TPUs, Trainium) with their specs, apps and websites, cloud and digital-banking platforms — with the metrics that may be passed on: a website's Chrome UX Report popularity bucket per country beside its peers (`web_popularity`) and a GPU cloud's live spot prices per GPU and region beside its on-demand price (`gpu_spot`, Nebius). Pass `company` for its list (latest readings), or `asset` (a `key` from that list) for one asset with its holders over time, lifecycle events, 24 months of CrUX history and the spot daily closes. Bank deposit rates, App Store ratings and ranks, and GPU rental prices exist in the terminal but are not served here (`withheld` says why). A CrUX bucket is a rank band of Chrome page loads, not traffic; a spot price is spare capacity, not what customers pay. Cite `source` / `attribution`. Data, not advice.", "paths": [ "/api/v1/companies/{id}/digital-assets", "/api/v1/digital-assets/{key}" ] }, { "name": "search_people", "title": "Search the people registry", "description": "Find people: company officers, directors and 10% owners from SEC Forms 3/4/5 (segment `corporate`, the default), government officeholders (`government`: US officeholders and members of Congress, and the UAE's rulers, ministers and emirate executive councils, ids AEGVP…), and central bankers (`central_bank`: Federal Reserve officials). Filter by name words, a company's ticker, role and whether they are current; sort by `accuracy` to list the executives with the most verified guidance. Each row carries the `id` `get_person` reads, the primary seat, shares held from Form 4 and, for executives, their guidance-scorecard counts. Use `get_person` for one person's record. Paged: `offset` = the previous `next_offset`. Cite each figure with its source (the Form 4 date and code, the meeting date, the call date and quote, the office's source link). A missing field or an empty section means not held or never filed, never zero. Data, not advice.", "paths": [ "/api/v1/people" ] }, { "name": "get_person", "title": "One person's record", "description": "One person from `search_people` (`id`: an SEC CIK such as 0001197649, or a platform key such as USGVP00025 / USFDP00005 / AEGVP00098), with the sections you ask for (`include`): `roles` (company seats with dates), `insider` (Form 4 cadence over 12 months, current holdings, the latest five trades), `transactions` (Form 4 history, filterable by date and code: P purchase, S sale, A award, M option exercise, F tax withholding, G gift), `scorecard` (the guidance they gave on earnings calls, each verified against the reported result: hit rate, guided range vs actual, the quote), `statements` (their tracked statements by call, verbatim), `speech` (calls spoken on), `shareholder_votes` (votes cast on their election as a director), `leadership` (8-K appointments and departures), `office` (public offices, official biography, Fed speeches), `votes` (a member of Congress's roll-call votes with the party-line summary). Default: roles, insider, scorecard, office, leaving out the SEC sections (roles, insider, scorecard) that hold nothing for the person — an official with no Form 3/4/5 filings gets `office` only, and `not_applicable` names what was left out; ask for a section by name to get it anyway. Lists are paged by `limit` (default 10); `offset` pages one list at a time. Use it for \"has X sold shares\", \"how accurate is X's guidance\", \"how does X vote\"; use `get_guidance` for a company's scorecard. A guided range is management's claim, not an Astreus estimate. No photos. Cite each figure with its source (the Form 4 date and code, the meeting date, the call date and quote, the office's source link). A missing field or an empty section means not held or never filed, never zero. Data, not advice.", "paths": [ "/api/v1/people/{cik}", "/api/v1/people/{cik}/transactions", "/api/v1/people/{cik}/votes" ] }, { "name": "list_conflicts", "title": "Armed conflicts", "description": "Armed conflicts Astreus has published: so far the 2026 Iran war, the 2026 Houthi–Saudi war, the 2025–2026 Afghanistan–Pakistan war and the Russia–Ukraine war (the UCDP/PRIO 1946–2024 dataset and other records are under review and not served): name, kind (interstate, intrastate, internationalized_intrastate, extrasystemic; seeds also operation, crisis), region, location, start and end, intensity (minor: 25–999 battle deaths in a year; war: 1,000+), battle deaths, and the states that took part on either side. Filter by a `country` that was a party (ISO-2), region, kind, a year it was active (`active_in`), a date window it overlaps, `ongoing`, or words in the name. Read one conflict's parties by side with `get_conflict`. Paged: `offset` = the previous `next_offset`. Cite the conflict by name and id with `attribution` (UCDP/PRIO Armed Conflict Dataset (CC BY 4.0)). UCDP counts a conflict-year at 25 or more battle deaths; battle deaths are UCDP's best estimate with a low–high range. A null end means ongoing as of the data year (`ucdp_through`), a null death count means not estimated, never zero. Data, not advice.", "paths": [ "/api/v1/military/conflicts" ] }, { "name": "get_conflict", "title": "One armed conflict", "description": "One conflict from `list_conflicts` by `id` (`ucdp:14609`, or `seed:` for a reviewed Astreus record): every party on each side (primary belligerents and states supporting them with their own troops) with its years, opponents and outcome where a source states it; the years active, intensity, battle deaths (best, low, high), the incompatibility (territory or government), the conflict it continues and the rows that continue it, the dispute it sits in and the named events inside it, and its sources. Use `list_conflicts` to find one or to filter by country. Cite the conflict by name and id with `attribution` (UCDP/PRIO Armed Conflict Dataset (CC BY 4.0)). UCDP counts a conflict-year at 25 or more battle deaths; battle deaths are UCDP's best estimate with a low–high range. A null end means ongoing as of the data year (`ucdp_through`), a null death count means not estimated, never zero. Data, not advice.", "paths": [ "/api/v1/military/conflicts/{key}" ] }, { "name": "get_organisation", "title": "International organisations", "description": "International organisations (UN bodies, development banks, standard setters, alliances, regional blocs, forums). Without `code`: the registry, filtered by words, `kind` or `domain`, each with its `code` and how many countries are members now. With `code` (IMF, OPEC, GCC, FATF, WBG, …): what it is, its parent and child bodies, its member countries with joining dates and status (members: current, all or none), member organisations, and agreements it is party to. With `code` and `member` (ISO-2): that country's seat history, the organisation's measured series for it, and its financing instruments (World Bank loans, credits and grants with commitments and disbursements; paged). Organisations serve only once reviewed: an empty registry or a not-found means not yet released, not that the organisation does not exist. Not included: BIS banking statistics (may not sit behind a paid tier), IMF financing and IMF/UN-licensed series, the UN treaty list and rows sourced only from UN sites (written terms not yet filed). Cite each figure with its source and period. Missing is not zero: a null means not held. Never net cooperation against friction, never sum \"up to\" or pledged money. Data, not advice.", "paths": [ "/api/v1/foreign-relations/organisations", "/api/v1/foreign-relations/organisations/{code}", "/api/v1/foreign-relations/organisations/{code}/countries/{iso2}" ] }, { "name": "get_government", "title": "Government, one sub-tab or one part at a time", "description": "A country's government, structured like its page. `section` reads one Government sub-tab in one bounded call, each part with its newest rows (`limit` per part, default 5; officials 25 holders) and the `view` call that reads that part in full. US: `administration` (officials, appointments and departures, executive orders, other presidential documents, Federal Register rules, Regulations.gov dockets), `congress` (members, committees, hearings, roll-call votes, bills, bills per month, next sittings), `judiciary` (Supreme Court, federal courts, judges, opinions, advocates), `fiscal` (the federal budget flow and USAspending awards, which the page draws under Economy › Fiscal). A registry country (AE today): `administration` (the Federal Supreme Council and federal executive, appointments and departures, federal entities), `regional_governments` (each emirate's executive council and entities), `legislature` (the Federal National Council). `get_country` lists a country's sections. `view` reads one part in full, paged (default 20, max 100; `offset` = the previous `next_offset`, per list under `pages`). Legislature (US): `members` of Congress, `committees` (pass `committee` = its systemCode for one committee's roster and meetings), printed `hearings`, recent roll-call `votes` (pass `congress`, `chamber`, `session`, `roll` for how every member voted), `bills` (by `congress`, `stage`, `voted`, words), `bills_monthly`, `next_sitting`. Executive and regulation (US): `executive_orders` (1994 on, by administration `era`), `executive_orders_monthly` (per month: executive orders, other presidential documents and GovInfo compilation packages, with each series' total), `presidential_documents`, `regulation` (Federal Register rules), `dockets` (Regulations.gov). Money (US): `spending` (largest USAspending prime awards and totals by agency, US dollars), `spending_recipients`, `budget` (Treasury receipts by source and outlays by function per fiscal year, billions of dollars). `feed` (US): the newest records across the congress.gov, Federal Register, Regulations.gov and USAspending lanes; it is on no page sub-tab. Any country with a registry (AE): `entities` (filter by `level`, `region`, `kind`), `entity` (one entity by `code`: head, owned and regulated listed companies, children, its laws a page at a time), `officials` (who holds each office now, or at an administration `era`; `body` picks bodies; paged by holder with `limit` / `offset`, and `bodies` lists every body with its holder count), `official_changes` (arrivals and departures, by `since`/`until`, `era`, `change`). Courts (US): `judiciary_scotus`, `judiciary_courts`, `judiciary_judges`, `judiciary_opinions`, `judiciary_advocates`. Use `get_calendar` (kind congressional) for meetings between two dates and `list_macro_series` for an entity's statistics; `query` filters the rows a view holds (its latest window), not the whole archive. Cite each row's own link (url, sourceUrl, htmlUrl, pdfUrl) or the result's `source`. A missing row, field or count means not held, never zero; `available: false` means the country is not covered, and `load.isSample: true` means the rows are a pilot sample. Data, not advice.", "paths": [ "/api/v1/countries/{iso}", "/api/v1/countries/{iso}/government/{view}", "/api/v1/countries/{iso}/government/bills", "/api/v1/countries/{iso}/government/bills/monthly", "/api/v1/countries/{iso}/government/executive-orders", "/api/v1/countries/{iso}/government/executive-orders/monthly", "/api/v1/countries/{iso}/government/next-sitting", "/api/v1/countries/{iso}/government/committees/{systemCode}", "/api/v1/countries/{iso}/government/votes/{congress}/{chamber}/{session}/{roll}", "/api/v1/countries/{iso}/government/entities", "/api/v1/countries/{iso}/government/entities/{code}", "/api/v1/countries/{iso}/budget-flow", "/api/v1/countries/{iso}/officials", "/api/v1/countries/{iso}/officials/changes", "/api/v1/countries/{iso}/judiciary/{view}" ] }, { "name": "get_central_bank_financials", "title": "Federal Reserve Banks' financial statements (US only)", "description": "US only — it takes no country: the Federal Reserve Banks' own financial statements, as the Board publishes them (for the Central Bank of the UAE's balance sheet use `get_central_bank` with iso AE, section financials): `statements` = the balance sheet (statement of condition), the income statement and the 1914-to-date income summary, for the 12 Banks combined (annual FY1995–2025, quarterly 2012–2026) or one Bank (`entity`, annual). Values are USD millions as printed (a dash printed is zero); there is no cash-flow statement (the Banks are exempt). By default the newest 10 annual or 8 quarterly columns; set `from` / `to` (period end) or `last`, and `statement` for one statement. `quality.withheld` names the columns a gate held back: a missing cell is withheld or not presented, never zero. `notes` = the note tables of one document (without `table`: the index of its tables and the entity's documents; with `table`: that table's figures, each with its page). `source` = where one figure was printed: every document vintage of that cell (pass `statement`, `line` = the row key, `period_end` = the column's endDate, `duration` = its durationMonths), served first — cite that document and page. For the Fed's policy text use `search_policy_text`; for rates and balance-sheet series use `get_macro_series`. US only. Data, not advice.", "paths": [ "/api/v1/countries/{iso}/fed-financials", "/api/v1/countries/{iso}/fed-financials/notes", "/api/v1/countries/{iso}/fed-financials/source" ] }, { "name": "list_countries", "title": "Country screener", "description": "Countries side by side with their latest headline figures: population (persons), nominal GDP (billions of US dollars, and of the local currency where held), real GDP growth (where a real series is held; null otherwise) beside nominal GDP growth (always: the change in nominal GDP on the same period a year earlier — not real growth), inflation and government debt to GDP (all percent). `periods` gives each figure's period. Filter by `region` (a region or sub-region: Asia, Western Asia, Europe, …) or words in the name or ISO code, rank by `sort` (largest first; `order` asc for the smallest; nulls last) and page with `offset` = the previous `next_offset`. Use it to compare or rank countries; use `get_country` for one country's profile and `get_macro_series` for a figure's history and exact period. Each figure carries its publisher in `sources` — cite it. A null figure is not held, never zero; figures from different countries can be for different periods (read `periods`). Data, not advice.", "paths": [ "/api/v1/countries" ] }, { "name": "get_research_widget", "title": "Filing diff, XBRL structure, data confidence", "description": "Three research readouts for one SEC registrant (US filers only: a Gulf platform key such as XDFM000004 is refused, since these read SEC 10-K / 10-Q sections and XBRL): `filing_diff` (each section of the latest 10-K and 10-Q against the previous filing of the same form: changed or unchanged, the word-count change, and a summary or preview; an empty diff says which filing lacks parsed sections), `statement_xray` (the latest XBRL filing's presentation tree with how many calculation links each node carries, 160 nodes a page: `page.total` is the whole tree and `offset` = page.next_offset reads the next nodes), `data_confidence` (the parser's validation issues on the company's filings, with severity and whether each is resolved). Use `get_filing_sections` / `get_section_text` to read a section, `get_financials` for the figures and `get_fact_source` to cite one. Values are display strings as the terminal shows them. Cite the filing type and date on each row. Data, not advice.", "paths": [ "/api/v1/research/widgets/{kind}", "/api/v1/companies/{id}" ] }, { "name": "get_document_text", "title": "Read a filing, report or presentation as text", "description": "The text of any document `list_filings` or `get_presentations` lists, read whole and in order: SEC 10-K, 10-Q, 8-K, proxy and their exhibits; exchange and regulator documents (annual and interim financial statements, integrated and annual reports, board and AGM notices, press releases, EDINET / DART / ESEF packages); results and investor presentations. `document` is the accession number (SEC) or the document reference (e.g. EMAARIR-2026Q2-PRES, DFM-EMAAR-2026Q2-FS) exactly as listed. Pages are marked \"[page N]\": the PDF page, the sheet of an SEC filing as its HTML breaks it, or the slide; `pages_in_text` gives the pages a window covers. Read on with `offset` = the previous `next_offset` until it is null, or jump with `page_from` / `page_to`. SEC filings return the primary document; `parts` lists the exhibits (EX-99.1 press release, EX-99.2 deck or CFO commentary, …): read one with `part` (its type, or its file name when a type repeats). For an 8-K deck from `get_presentations` pass its `document` and `part`. `text_source` says where the text comes from: html (the filing's own HTML), sgml_text (a pre-2001 text filing), json (an exchange announcement), pdf_extracted (the PDF's text layer), stored_extraction (the platform's extraction, OCR or vision transcription of a scan included; `stored_as` names which), ocr (the platform's OCR of a scan). `text_unavailable` means the document has no text to read (slide images, a scan nobody OCR'd, a recording): say so and name the reason; never reconstruct its contents. Use `get_section_text` for one parsed section (MD&A, risk factors), `get_event_text` for one 8-K item, `get_note_tables` for the tables in the notes and decks, and `get_transcript` for earnings calls. Without `id`, an SEC accession alone reads that filing's primary document (any completed EDGAR filing, including a fund manager's 13F that is no company's own; `issuer` keeps the 13F holdings whose issuer name contains it), windowed by `offset` / `max_chars` but without page markers or exhibits. Quote the text as the issuer's own words, with the document reference and page; a figure absent from the text is not available, never 0. Data, not advice.", "paths": [ "/api/v1/companies/{id}/filings/{accession}", "/api/v1/filings/{accession}" ] }, { "name": "list_companies", "title": "List published companies by country, sector or name", "description": "The published companies Astreus serves, filtered and ranked: `country` (ISO-2: US, SA, AE, KW, QA, JP, …), `sector` (the sector name as rows show it, e.g. \"Financial Services\"), `query` (name, legal name or ticker contains, plus the closest search matches), `scope` (public = listed companies, default; private = the private-company lane, platform keys XPRV…; all). Largest market cap first by default; `sort` market_cap, name or pe with `direction`. Paged: `limit` (default 50, max 150) and `offset` = the previous `next_offset` (null on the last page); `total` counts every match and `countries` the matches per country. Each row's `id` is what the company tools take (the ticker for an SEC registrant, else the platform key such as XDFM000001). `market_cap_usd` is in US dollars; for a private company it is its latest reported valuation (`private` names the round and date), not an exchange quote. Prices, changes and volumes are not given here. Use `search` to resolve one name, `get_company` for one company's profile and metrics, `get_coverage` for what each market holds. A null field is not available, never 0. Data, not advice.", "paths": [ "/api/v1/companies" ] }, { "name": "get_chart_series", "title": "Chart series: align macro, fundamentals and commodity prices on one calendar", "description": "Puts up to eight series side by side on one calendar, each with a transformation, for comparing them: a US macro indicator (kind macro, `indicator_code`), a company fundamental from its statements (kind company_fundamental: `company`, `metric` such as revenue, net_income, capex, eps_diluted, `period_basis` annual or quarterly), or a commodity price (kind commodity_price, `symbol`). `frequency` native (default: each series at its own frequency) or daily, weekly, monthly, quarterly, annual to align them (a finer series rolls up by its `aggregation`: last, mean or sum); `transformation` none, pct_change, yoy_pct_change (percent), first_difference, log, z_score or rolling_volatility; `from` / `to` bound the dates. Each series comes back with its units, source and points (date, value). Catalog mode lists what can be charted: `catalog` macro (indicator codes with name, units, frequency and history span), fundamentals (companies with fundamentals, and the metric keys) or commodities (symbols), narrowed by `query` and paged by `limit` / `offset` (next_offset). Pass `catalog` or `series`, not both. Stock and index prices are not served here (licence), and an Ornn OCPI GPU index comes back withheld. For one macro series with its revisions use get_macro_series, for whole statements get_financials, for one commodity's full history get_market_series. Cite each series' `source`; a missing point is not available, never 0. Data, not advice.", "paths": [ "/api/v1/charting/series", "/api/v1/correlation/catalog" ] } ] }