# Versioning & Changelog

## Versioning

The API is versioned in the path — the current version is **`/v1`**. We follow a simple contract:

- **Additive changes are non-breaking** and ship within `v1` without notice: new endpoints, new
  optional parameters, and new response fields. In particular, **new trailing-return periods**
  appear under `extra_returns` (see [Field reference](/fields)) so your client never breaks when a
  period is added upstream.
- **Breaking changes** — removing or renaming a field, changing a type, or altering existing
  behavior — would ship under a **new version path** (`/v2`), with the prior version supported
  during a deprecation window.

**Build defensively:** read known fields by name, ignore unknown fields you don't use, and don't
assume the return-period list is fixed.

## Changelog

### v1.0.0 — Initial release

- `GET /v1/funds` — search and list the fund universe (cursor pagination).
- `GET /v1/funds/{code}` — fund metadata.
- `GET /v1/funds/{code}/trailing-returns` — trailing returns (latest or `as_of`).
- `POST /v1/trailing-returns/batch` — trailing returns for up to 100 funds.
- `GET /v1/funds/{code}/calendar-returns` — calendar-year return (latest or `year`).
- `POST /v1/calendar-returns/batch` — calendar-year returns for up to 100 funds.
- Hosted MCP server at `/mcp` exposing all six operations as tools.
- 16 trailing-return periods (`1d`–`20y`, `ytd`, since-inception) and calendar-year returns for
  ~32,000 US mutual funds and ETFs.

_New entries are added here as the API evolves._