# Financial Data API

> Raw-first, derived-ready financial data infrastructure API. Macro, rates, FX reference, COT positioning, economic calendar, SEC fundamentals, and derived analytics from official / public-domain sources — designed to be consumed by LLM agents.

- Base URL: http://api.financialdatapi.com
- Version: 0.1.0
- Auth: send `x-api-key: <key>` (or `Authorization: Bearer <key>`). Scopes: `data:read`, `ops:read`, `admin`. `/health`, `/ready`, `/openapi.json`, `/llms.txt`, `/llms-full.txt` need no key.
- Response envelope: `{ data, meta: { request_id, api_version, pagination }, requestId }`. Errors: `{ error: { code, message, request_id }, requestId }` with stable codes (`bad_request`, `not_found`, `unauthorized`, `forbidden`, `rate_limited`, `internal_error`). Unknown query params are rejected with `bad_request`.
- Pagination: cursor-based — `limit` (1–500, default 100), `cursor`; responses carry `meta.pagination.next_cursor` and `has_more`.
- Time model: `period`/`period_start`/`period_end` filter the *period* a value describes; `start_date`/`end_date` filter *knowledge-time* (`observed_at`); `as_of` returns the latest vintage known on or before a timestamp.
- Read-only: every endpoint is `GET`.

## Service & machine resources

- GET /health — Health check
- GET /llms-full.txt — LLM full API reference
- GET /llms.txt — LLM documentation index
- GET /openapi.json — OpenAPI document
- GET /ready — Readiness check

## Public data (redistribution-safe)

- GET /v1/public/companies — List scored companies
- GET /v1/public/coverage — Get coverage summary
- GET /v1/public/observations — List public observations
- GET /v1/public/observations/latest — List latest public observations
- GET /v1/public/screener — Screen entities by macro indicator values
- GET /v1/public/screener/filters — List screener filter fields

## Observations & provenance

- GET /v1/derived-observations — List derived observations
- GET /v1/observations — List observations
- GET /v1/observations/changes — List changed observations
- GET /v1/observations/latest — List latest observations
- GET /v1/provenance/observations/{observationId} — Get observation provenance

## Sync (manifest, snapshot, changes)

- GET /v1/manifest — Get sync manifest
- GET /v1/snapshot — Get sync snapshot
- GET /v1/source-health — List source health

## Indicators

- GET /v1/canonical-indicators — List canonical indicators
- GET /v1/derived-indicators — List derived indicators
- GET /v1/derived-indicators/{idOrSlug} — Get derived indicator
- GET /v1/derived-indicators/{idOrSlug}/observations — List derived indicator observations
- GET /v1/indicators — List indicators
- GET /v1/indicators/{idOrSlug} — Get indicator
- GET /v1/indicators/{idOrSlug}/aliases — List indicator aliases
- GET /v1/indicators/{idOrSlug}/entities — List indicator entities
- GET /v1/indicators/{idOrSlug}/series — List indicator series
- GET /v1/indicators/{indicatorId}/observations — List indicator observations

## Entities, countries, companies & instruments

- GET /v1/companies — List companies
- GET /v1/companies/{idOrLookup} — Get company
- GET /v1/companies/{idOrLookup}/financials — Get company financial statements
- GET /v1/companies/{idOrLookup}/profile — Get company profile
- GET /v1/countries — List countries
- GET /v1/countries/{idOrIso} — Get country
- GET /v1/countries/{idOrIso}/available-indicators — List country indicators
- GET /v1/entities — List entities
- GET /v1/entities/{entityId}/derived-observations — List entity derived observations
- GET /v1/entities/{entityId}/observations — List entity observations
- GET /v1/entities/{idOrSlug} — Get entity
- GET /v1/entities/{idOrSlug}/aliases — List entity aliases
- GET /v1/entities/resolve — Resolve entity by alias
- GET /v1/instruments — List instruments
- GET /v1/instruments/{idOrLookup} — Get instrument

## Sources & providers

- GET /v1/providers — List providers
- GET /v1/providers/{providerId} — Get provider
- GET /v1/sources — List sources
- GET /v1/sources/{sourceId} — Get source

## Calendar & official events

- GET /v1/economic-calendar — List economic calendar events
- GET /v1/economic-calendar/{eventId} — Get economic calendar event
- GET /v1/events — List official events
- GET /v1/events/{eventId} — Get official event

## Derived analytics

- GET /v1/platform/macro-data — List platform macro data

## Operations (ops:read)

- GET /v1/api-usage — List API usage events
- GET /v1/connector-health — List connector health
- GET /v1/ingestion-jobs — List ingestion jobs
- GET /v1/ingestion-runs — List ingestion runs
- GET /v1/operational-events — List structured operational events
- GET /v1/ops/alerts — Get alert policy evaluation
- GET /v1/ops/connectors — Get connector operations summary
- GET /v1/ops/jobs — Get scheduler jobs operations summary
- GET /v1/ops/liveness — Get series liveness report
- GET /v1/ops/quality — Get quality operations summary
- GET /v1/ops/series-candidates — Get series replacement candidates
- GET /v1/ops/summary — Get operations summary
- GET /v1/ops/usage — Get API usage operations summary
- GET /v1/quality-issues — List quality issues

## Administration (admin)

- GET /v1/admin-sessions — List admin sessions
- GET /v1/api-clients — List API clients
- GET /v1/api-keys — List API key posture records
- GET /v1/backup-manifest — Get backup manifest
- GET /v1/quarantine — List quarantined records
- GET /v1/rate-limits — List rate-limit policies
- GET /v1/raw-payloads — List raw payload archive records
- GET /v1/readiness — Get readiness
- GET /v1/retention-policy — List retention policy records

## More

- Full machine-readable reference: http://api.financialdatapi.com/llms-full.txt
- OpenAPI 3.1 document: http://api.financialdatapi.com/openapi.json