> ## 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.

# Financial Data API for AI agents

> Why Financial Data API is agent-native, and the three ways an agent consumes it.

Financial Data API is macro and global-markets data infrastructure built to be read and called by LLM agents, not only by humans. It serves official and public-domain macro indicators, rates and yields, FX reference rates, the economic calendar, SEC fundamentals, and derived analytics as predictable JSON, with per-observation provenance and rights metadata.

Every endpoint is read-only and `GET`. Every response shares one envelope. Every error carries a stable, machine-readable code. That consistency is what makes an agent reliable against the API: it never has to guess the shape of a response or parse free-form error prose.

## Why Financial Data API is agent-native

<Columns cols={2}>
  <Card title="One predictable envelope" icon="layer-group">
    Every response is `{ data, meta, requestId }`. Lists carry `meta.pagination`. An agent learns the shape once and reuses it across every endpoint.
  </Card>

  <Card title="Stable error codes" icon="circle-exclamation">
    Errors return a machine-readable `code` (`bad_request`, `unauthorized`, `forbidden`, `not_found`, `rate_limited`, `internal_error`) plus a `requestId`. Unknown query params fail closed with `bad_request` rather than being silently ignored, so a typo surfaces instead of returning wrong data.
  </Card>

  <Card title="Discoverable by design" icon="file-lines">
    `GET /llms.txt` and `GET /llms-full.txt` describe the entire API as plain text an agent can read with no key. `GET /openapi.json` is the OpenAPI 3.1 source of truth.
  </Card>

  <Card title="Auditable provenance" icon="link">
    Observations carry source attribution, source URL, freshness, a raw payload reference, and rights metadata. `GET /v1/provenance/observations/{observationId}` returns the full chain from official release to API response, so an agent can cite where a number came from.
  </Card>
</Columns>

## The three ways an agent consumes Financial Data API

<Steps>
  <Step title="Native MCP server" icon="plug">
    The Financial Data API Model Context Protocol server exposes the API as read-only tools (`screen_macro`, `get_latest_observations`, `cross_country`, `rates_analytics`, `observation_provenance`, and more). Add it to Claude Code, Claude Desktop, or Cursor and your agent can query macro data conversationally with no glue code. This is the lowest-friction path for a chat-driven agent.
  </Step>

  <Step title="Self-describing text indexes" icon="file-lines">
    Point an agent at `/llms.txt` for a compact, sectioned index of every endpoint, or `/llms-full.txt` for the full reference with parameters. Both need no API key and stay in lock-step with the OpenAPI spec. An agent can fetch one, learn the surface, then call endpoints directly with HTTP.
  </Step>

  <Step title="Typed SDK" icon="code">
    The `@financialdatapi/client` TypeScript SDK wraps the same envelope and errors. It constructs with your `apiKey`, throws a typed `FinancialDataApiError` on non-2xx, auto-paginates cursor pages via an async iterator, and ships a `buildScreenerFilter` helper for the screener DSL. Use it when your agent runs inside a TypeScript or JavaScript runtime.
  </Step>
</Steps>

## Base URL and auth

All paths are relative to `https://api.financialdatapi.com`. Send your key as `x-api-key: <key>` or `Authorization: Bearer <key>`.

The following endpoints need no key: `GET /health`, `GET /ready`, `GET /openapi.json`, `GET /llms.txt`, `GET /llms-full.txt`. Everything under `/v1` requires a key.

<Info>
  Create an API key at [app.financialdatapi.com](https://app.financialdatapi.com): sign up, verify your email, and it is active immediately, with no card required. Keys are SHA-256 hashed server-side and never returned.
</Info>

## Conventions an agent should know

* **Envelope.** Lists return `{ "data": [...], "meta": { "request_id", "requestId", "api_version", "pagination" }, "requestId" }`. Items return `{ "data": { ... }, "meta": { ... }, "requestId" }`.
* **Pagination.** Cursor-based: `limit` (1 to 500, default 100) and an opaque `cursor`. Follow `meta.pagination.next_cursor` while `has_more` is `true`.
* **Time model.** `period` / `period_start` / `period_end` filter the period a value describes (for example May 2026 CPI). `start_date` / `end_date` filter knowledge-time (`observed_at`, when the value became known). `as_of` returns the latest vintage known on or before a timestamp; revisions are retained, never overwritten.
* **Rights-aware.** `/v1/public/*` returns only redistribution-safe official and public-domain data. Licensed vendor data is internal-only and never appears on the public surface.
* **Read-only.** Every endpoint is `GET`.

<Note>
  `as_of` currently approximates the ingestion timestamp, not a full provider-vintage reconstruction. Full vintage reconstruction is future work. Treat `as_of` as "known to Financial Data API on or before this time" rather than "published by the provider on or before this time".
</Note>

## Latest readings in one call

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl "https://api.financialdatapi.com/v1/public/observations/latest?country=USA" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```python Python theme={"theme":"css-variables"}
  import requests

  BASE = "https://api.financialdatapi.com"
  res = requests.get(
      f"{BASE}/v1/public/observations/latest",
      params={"country": "USA"},
      headers={"x-api-key": "your_key_here"},
  )
  res.raise_for_status()
  print(res.json()["data"])
  ```

  ```typescript TypeScript theme={"theme":"css-variables"}
  import { FinancialDataApiClient } from "@financialdatapi/client";

  const financialdatapi = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });
  const { data } = await financialdatapi.getLatestObservations({ country: "USA" });
  console.log(data);
  ```
</CodeGroup>

To see the live breadth of what is covered (catalog totals, public indicator categories, covered countries), call `GET /v1/public/coverage` rather than relying on a number hard-coded in docs.

## Next steps

<Columns cols={2}>
  <Card title="MCP server" icon="plug" href="/ai-agents/mcp-server">
    Add Financial Data API's read-only tools to Claude Code, Claude Desktop, or Cursor.
  </Card>

  <Card title="llms.txt" icon="file-lines" href="/ai-agents/llms-txt">
    The keyless, self-describing indexes an agent reads to discover the API.
  </Card>
</Columns>