Astreus1.What the API is
Astreus is a financial data terminal that turns the world's unstructured financial disclosure — filings, results announcements, investor presentations, earnings calls, 8-Ks and central-bank text across the US, the Gulf, Japan, Taiwan, Korea and Europe — into structured, traceable data, and this API serves everything the terminal renders, as JSON, under https://astreus.ai/api/v1: standardized statements, segments and KPIs, note tables, filing sections, decks, transcripts, guidance scorecards, 8-K events, news, ownership, people, point-in-time macro and a validated claim graph. The distinguishing property is traceability: every number links back to the fact, filing, page or passage it came from, and only data that has passed per-company validation gates is served. What is covered is itself an endpoint: GET /api/v1/landing/coverage (no key) lists every market and data type with the periods held.
The full contract is /openapi.json. This page explains the parts a spec cannot: how to authenticate, what the numbers mean, and how to fail well.
2.Authentication
Endpoints are tiered. public endpoints (coverage stats, logos, photos, health) need no credentials. Everything else takes an API key: create one on the Developers page in the terminal (any account — the Free plan needs no card) and send it on every request:
curl -s https://astreus.ai/api/v1/companies/NVDA \ -H "X-API-KEY: pk_live_YOUR_KEY"
Authorization: Bearer pk_live_… is accepted as an equivalent. Keys are shown once at creation and stored only as hashes; revoke or rotate them from the same page. Revocation takes effect within a minute.
Plans: Free — 30 req/min, 250 req/day. Build — 300 req/min, 100,000 req/month. Scale — custom. Build and Scale are set up with our team rather than self-serve — contact sales. Terminal Pro subscribers get Build limits included. A 402 upgrade_required marks a Pro-only surface.
Terminal sessions
3.Endpoints
{id} is a ticker symbol (NVDA), a numeric SEC CIK, or a platform key for a non-SEC issuer (XSAU000001 — Tadawul, DFM, ADX, Boursa Kuwait, QSE, TSE, TWSE, KRX and European exchanges are covered). A bare ticker resolves to the SEC registrant; the platform key is the cik field of the company payload. The most used routes:
| get | /search?q= | Resolve a name to a company (ticker + key), macro series or country. |
| get | /companies?country= | Browse a market; the response carries per-country counts. |
| get | /companies/{id} | Profile, sector, latest filing, quote, key metrics, accounting bases, corporate lineage. |
| get | /companies/{id}/financials | Standardized statements, ratios, segments & KPIs. period_type=annual|semiannual|quarterly; reporting_basis=individual (discrete quarters) | as_reported (cumulative year-to-date). |
| get | /companies/{id}/financials/as-filed | The statement exactly as the company printed it; vintage=original|latest; format=json|csv|xlsx. |
| get | /companies/{id}/fact-source | The fact, filing accession and arithmetic behind any cell — statements, segments and KPIs. Use it to cite. |
| get | /companies/{id}/segment-revenue | Latest revenue by segment, product, brand or channel; /regional-revenue by geography. Deck-sourced blocks say so. |
| get | /companies/{id}/filing-notes | Parsed sections (MD&A, risk factors, …) with text at /{sectionId}; note tables at /tables and /tables/{tableId}; a family across filings at /series?family=. |
| get | /companies/{id}/presentations | Investor decks, newest first; slide images at /{presentationId}/pages/{page}. |
| get | /companies/{id}/filings | Paginated filing index; /filings/{accession} returns the document itself (HTML, PDF or media). |
| get | /companies/{id}/events | 8-K material events typed by family; /events/wire searches across the universe. |
| get | /companies/{id}/earnings/promises | Guidance commitments extracted from calls; /earnings/scorecard says whether they were met. |
| get | /companies/{id}/transcripts | Earnings-call transcript index; text, audio and span-anchored annotations per call. |
| get | /companies/{id}/ownership | 13F holders and insider transactions (Forms 3/4/5); /management for boards and votes; /people for the registry. |
| get | /countries/{iso}/series?key= | Point-in-time macro history for one series (FRED/ALFRED vintages); /policy-text for central-bank text. |
| get | /news/feed | The attributed intraday news tape; /news/stream for Server-Sent Events. |
| get | /intelligence/company/{id}/claims | Causal claims made by or about a company, each with its claim-graph edge and declared validation status. |
| get | /indices, /commodities | Benchmarks, sector ETFs, commodities and compute (GPU rental) prices. |
The human-readable guide to every dataset — coverage, statements, segments and KPIs, filing notes, presentations, transcripts, events, ownership, macro, intelligence — is at doc.astreus.ai.
Routes under /watchlists, /workspace, /billing and /developer are account-owned or operator surfaces and are not part of the documented contract.
4.Data semantics
Vintages. financials returns the latest restated values, because that is what a later filing says the period was, and fact-source names the filing each value came from. What the company originally filed is financials/as-filed with vintage=original. reporting_basis=as_reported is a period basis — the cumulative year-to-date quarter — not a vintage. Macro series are bitemporal: the value for a date is what was known on that date, never a later revision.
Missing is not zero. A null line means the serving gate withheld it or the company never reported it. Treat it as unavailable.
Derived quarters. Most US filers do not file a Q4 10-Q; the fourth quarter is derived from the annual total minus the first three quarters and is marked as derived in the payload.
Provenance. Financials come from SEC EDGAR XBRL, reconciled against the SEC companyfacts API, and from the statements exchange-lane issuers publish (inline XBRL, HTML or PDF — the provenance field names the lane). Macro data is FRED/ALFRED. Transcripts come from licensed providers and issuer sites. /fact-source closes the loop from any number to its filing.
5.Rate limits and errors
Limits are per plan, enforced in fixed UTC windows across all instances: Free — 30/min and 250/day; Build — 300/min and 100,000/month. Every API-key response carries RateLimit-* headers (and X-Quota-* on quota-carrying plans); a 429 carries Retry-After. Fetch a whole statement once rather than line by line.
Errors are JSON: {"error": "...", "code": "..."}. Stable codes: unauthenticated (401), upgrade_required (402), rate_limited and quota_exceeded (429). Branch on the code, not the message.
6.For AI agents
Astreus publishes the conventional machine-readable files so an agent can discover and use the API without scraping the terminal:
| openapi.json | OpenAPI 3.1 contract for every public and free-tier endpoint, including tiers, parameters and request bodies. |
| llms.txt | Plain-text overview of the site and API for language models, following the llms.txt convention. |
| agents.md | What an agent may do here: callable endpoints, authentication, and the rules (cite sources, respect vintages, no advice). |
| skill.md | A step-by-step playbook for answering a financial question with Astreus data and citing the filing behind each number. |
| mcp.json | MCP discovery manifest for the hosted server at /api/mcp (Streamable HTTP; API key or OAuth 2.1) and the local stdio server shipped with the CLI (`astreus mcp`). Same keys, same limits as REST. |
The rules in agents.md are the short version of this page: cite the filing behind every number, respect vintages, never present a gap as zero, and give no advice.
7.Not advice
Data, not recommendations