API and MCP docs

Make a first call

The API is JSON over HTTPS. This call returns Apple's last five annual income statements. It needs no key.

curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"

The statement is one of income_statement, balance_sheet, cash_flow or supplemental. The period type is one of annual, quarterly, ltm or ytd.

Name a company

Every company route takes a company parameter.

• ticker:AAPL, or ticker:AAPL.XNAS to name the exchange
• cik:320193, the SEC's company number
• fmd_<id>, the id FinancialMD gives the company

A bare AAPL is read as a ticker and bare digits as a CIK. The response says what matched in meta.company.matched_by.

Read a value

A successful response is { data, meta }. A number inside data is never bare. It is a value object:

{
  "value": 391035000000,
  "unit": "USD",
  "currency": "USD",
  "decimals": -6,
  "period": { "start": "2023-10-01", "end": "2024-09-28", "type": "annual", "fiscal_year": 2024, "fiscal_period": "FY" },
  "known": { "from": "YYYY-MM-DDThh:mm:ssZ", "to": null },
  "restated": false,
  "method": "as_filed",
  "calc_type": "as_filed",
  "proof": { "id": "p_...", "accession": "0000320193-24-000123", "form": "10-K", "filed": "2024-11-01", "taxonomy": "us-gaap", "tag": "...", "source_url": "https://www.sec.gov/..." }
}

known is the time span in which this was the latest filed figure. restated is true only when a later filing changed the figure; restatement_kind then says how. proof.id resolves at GET /proof/{id} to the filing and the raw facts behind the value.

Read the past as it was known

• as_of=2024-06-30 on any read route returns what was known at that instant.
• original=true returns the first-reported version of each period.
• history=true returns every version of each period, oldest first.
• GET /v1/changes?since=<timestamp> lists facts learned since then.

Routes

The OpenAPI document has every parameter and response schema. The llms.txt, llms-full.txt and skill file say the same for agents; https://api.financial.md/docs is the interactive reference and https://api.financial.md/changelog lists changes.

Check a number

curl -X POST "https://api.financial.md/v1/verify" -H "content-type: application/json" \
  -d '{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000}'

The answer has a verdict of matches, differs or unknown, the filed value with its proof, the difference, and a scale_hint when your number is off by a power of ten.

Limits

Calls without a key are limited per IP address, per day.

• 25 metered calls: ratios, screen and verify
• 1,000 filing-layer reads: statements, as-reported facts, filings, ownership and prices
• 1,000 metadata reads: directory, profiles, metrics, proofs and changes

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 carries Retry-After.

API keys with higher limits are not issued yet. See API keys. Nothing is charged today. See Pricing.

What is covered

Coverage is companies that file with the SEC and are listed on a US exchange today.

• Standardized statements exist for filers that report under US GAAP.
• Filers that report under IFRS, such as many foreign companies that file Form 20-F or 40-F, have filings but no standardized statements yet.
• Companies that were delisted are not loaded yet.
• Ownership data comes from filings made since July 1, 2026, and is updated every day at 13:00 UTC from the EDGAR daily index: insider transactions from Forms 3, 4 and 5 of covered companies, and every Form 13F-HR, so a new quarter's 13F reports arrive as managers file them. A 13F position is tied to a company only when a Schedule 13D or 13G cover names its security. For the quarter ended June 30, 2026 this ties 80 percent of the reported value; the other positions appear in a manager's portfolio under the issuer name as filed.
• Consensus estimates and earnings call transcripts are not served: both are licensed data. Segments are served as reported, and news is the feed of 8-K filings.

When a company is known but a dataset is missing, the API answers not_covered and lists the datasets it does have.

MCP server

The MCP server wraps the same API in 36 read-only tools. It speaks MCP Streamable HTTP and needs no account.

https://mcp.financial.md/mcp

The MCP guide lists the tools. The server card is for registries.

Errors

An error is { "error": { code, message, docs, request_id, remedies } }. The remedies list says what to do next. The error reference explains each code.