> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Notable changes to the Financial Data API, newest first.

This page records notable, user-facing changes to the Financial Data API. The contract itself always lives in [`openapi.json`](/api-reference/openapi.json), and live breadth is reported by [`/v1/public/coverage`](https://api.financialdatapi.com/v1/public/coverage).

<Update label="2026-07-05">
  Deeper history across positioning, valuation, and US housing. All items below are served through the existing `GET /v1/public/observations` route (`indicator_id` plus `entity` / `start_date` / `end_date`) and the `get_observations` MCP tool.

  **Data surface**

  * **COT positioning percentile history.** `cot_positioning_percentile` now serves its full weekly panel — 1992 to today, 244,944 rows across 972 CFTC contracts (delisted contracts retained as valid history) — instead of the latest value only. The value is the 3-year midrank percentile (0–100) of net non-commercial positioning, derived from CFTC legacy COT stored back to 1986. `valueText` flags `crowded_long` (at or above 90) and `crowded_short` (at or below 10); metadata carries `net`, `weeklyChange`, `percentile1y`, `percentile3y`, and `zScore3y`.
  * **New indicator: `cot_tff_percentile`.** The same percentile statistics over Traders in Financial Futures leveraged-funds net positioning: weekly, 2006 to today, 41,398 rows across 117 financial futures (FX, rates, equity index). Same metadata shape.
  * **Valuation multiples: deep history.** All 13 trailing multiples (P/E, P/B, P/S, P/FCF, P/OCF, EV/EBITDA, EV/EBIT, EV/Sales, EV/FCF, earnings yield, FCF yield, dividend yield, PEG) now span 2007 to today — roughly 75,000 rows per headline multiple across \~500 US companies — computed from raw as-traded prices with point-in-time trailing-twelve-month fundamentals.
  * **US housing, deep and public.** `us_housing_starts` (monthly since 1959) and `us_building_permits` (monthly since 1960), both in thousands of units (SAAR), sourced from FRED `HOUST` and `PERMIT`.
  * **New indicator: `cb_statement_sentiment`.** Deterministic hawk/dove sentiment for every FOMC policy statement — 244 statements, February 1994 to today, keyed to `country_usa`. Score in \[−1, +1] from a versioned phrase lexicon (`fdapi_hawk_dove_v1`); `valueText` labels `hawkish` / `dovish` / `neutral`; metadata carries the matched phrases, counts, and `deltaVsPrior` for a full audit trail. December 2008 scores −1.0, June 2022 scores +1.0. See [Derived analytics](/apis/derived-analytics#fomc-statement-sentiment).
  * **OECD confidence, deep history.** `business_confidence` and `consumer_confidence` now reach back to 1960 where the OECD publishes it — about 43,000 rows across all covered countries (previously 2024 onward only).
  * **EIA energy series, full history.** All 13 EIA series now carry their complete published history: WTI spot since 1986, Brent since 1987, Henry Hub natural gas since 1997, and the weekly petroleum inventory, production, and refinery panels since 1982 where available.

  Plan history windows apply: free-tier keys see the trailing 24 months of any series. See [Derived analytics](/apis/derived-analytics) for worked examples.
</Update>

<Update label="v1.0.0">
  The first public release of the Financial Data API. The surface below is stable under `/v1`, and every response reports `meta.api_version = "v1"`.

  **Data surface**

  * **Macro observations.** Point-in-time, official-source macro readings. Redistribution-safe data on `GET /v1/public/observations` and `GET /v1/public/observations/latest`; the full observation surface with attribution, freshness, and rights metadata on `GET /v1/observations`, `/v1/observations/latest`, and `/v1/observations/changes`.
  * **Screener.** `GET /v1/public/screener` filters countries and entities by latest canonical-indicator values, with the filter DSL fields discoverable at `GET /v1/public/screener/filters`.
  * **Coverage.** `GET /v1/public/coverage` returns a live breadth summary: catalog totals, public indicator categories, and covered countries.
  * **SEC fundamentals.** `GET /v1/public/companies` exposes the scored fundamentals universe (S\&P 500 union Nasdaq-100) with sector and industry inline. `GET /v1/companies/{idOrLookup}/financials` returns structured income, balance-sheet, and cash-flow statements from SEC XBRL.
  * **Derived analytics.** `GET /v1/derived-indicators` and `GET /v1/derived-observations` serve stored derived analytics, each carrying `inputObservationIds` and `sourceRefs`.
  * **Calendar and events.** `GET /v1/economic-calendar` and `GET /v1/events` (each with a `/{eventId}` detail route) cover the economic calendar and unified official events.
  * **Catalog routes.** `GET /v1/canonical-indicators`, `/v1/entities` (plus `/resolve`, `/{idOrSlug}`, and `/{entityId}/observations`), `/v1/countries` (plus `/{idOrIso}` and `/available-indicators`), and `/v1/indicators` (plus `/series` and `/entities`).

  **Trust and operations**

  * **Provenance.** `GET /v1/provenance/observations/{observationId}` returns an auditable chain from official release to API response: named source, source URL, raw payload reference metadata, and the ingestion run.
  * **Sync and manifest.** `GET /v1/manifest`, `/v1/snapshot`, and `/v1/source-health` support sync workflows and report source and connector freshness.
  * **Liveness.** `GET /v1/ops/liveness` runs a per-series cadence check to flag silently-frozen feeds.

  **Platform**

  * **Response envelope.** One shape for every response, with `data`, `meta`, and a `request_id` on success, and stable machine-readable `error.code` values on failure. Unknown query parameters fail closed.
  * **Bi-temporal time model.** Period filters describe the period a value covers; knowledge-time bounds and `as_of` describe when a value became known, with revisions retained, never overwritten.
  * **Authentication and scopes.** API keys via `x-api-key` or `Authorization: Bearer`, with `data:read`, `ops:read`, and `admin` scopes and per-scope rate limits.
  * **MCP server.** A native Model Context Protocol server with read-only tools (for example `screen_macro`, `get_latest_observations`, `cross_country`, `rates_analytics`, and `observation_provenance`) for Claude Code, Claude Desktop, and Cursor.
  * **TypeScript SDK.** The official `@financialdatapi/client` package with cursor auto-pagination and a `buildScreenerFilter` helper.
  * **Agent-readable index.** `GET /llms.txt` and `GET /llms-full.txt` publish a key-free API index for agents.
</Update>

<Note>
  This changelog starts at the first public release. Future entries will be added here, newest first, as the public surface changes.
</Note>