# Fundamentals

The `/v1/fundamentals` routes read the same normalized statements the
[`/v1/edgar`](https://docs.arche.fi/time-series) routes do, shaped for a different question. Where an
EDGAR route answers about one company, these answer about a set of them, and
where an EDGAR route puts the company in the path, these take it as a parameter
so one request can name several.

Nothing here is a second corpus. Every figure comes from the same normalized
statement versions, with the same provenance, so a value you read as a panel
reconciles with the same value read one company at a time.

## When to use this namespace

- `many companies, one request` (/v1/fundamentals): `ciks` or `tickers` is a repeatable parameter, so a panel of companies and
  metrics comes back in one paginated response.
- `one company, one metric` (/v1/edgar): `/v1/edgar/companies/{cik}/metrics/{metric}/time-series` is the narrower
  read, and the one to use inside a per-company loop.
- `pinned to a date` (/v1/edgar/as-of): Neither namespace is a point-in-time snapshot. When the question is what was
  knowable on a date, use
  [as-of financials](https://docs.arche.fi/guides/point-in-time-research).
- `persisted model rows` (/v1/modeling): These routes compute on read. The [modeling](https://docs.arche.fi/modeling) routes serve rows
  built against a stored snapshot.

## Panels across companies

`statement_type` is required. Name companies with `ciks` or `tickers`, not both,
repeating the parameter once per company:

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/time-series?statement_type=INCOME_STATEMENT&tickers=AAPL&tickers=MSFT&metrics=REVENUE&metrics=NET_INCOME&frequency=annual&page_size=50" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

- `metrics` (repeatable, optional): A subset of canonical metric names. Omit it and every metric present in the
  statements comes back, which is the larger response.
- `use_tier1_only` (boolean): With `metrics` omitted, restricts the panel to the Tier-1 canonical set
  instead of everything present.
- `frequency` (annual | quarterly): `annual` covers FY periods and `quarterly` covers Q1 through Q4. Annual is
  the default.
- `from, to` (date): Bound the span. Both are optional, and a wide span costs little more than a
  narrow one.

Metric names must be canonical. A derived name such as `GROSS_MARGIN` belongs to
the next route, and the [metric catalog](https://docs.arche.fi/metrics) says which is which.

## Derived panels

The same panel shape, for figures computed from the canonical facts rather than
mapped from a filing: margins, growth, cash-flow conversion and returns.

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/derived/time-series?statement_type=INCOME_STATEMENT&tickers=AAPL&metrics=GROSS_MARGIN&frequency=annual" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

This is on-the-fly computation over normalized statements. It is not the
modeling warehouse, so it needs no snapshot to exist first, and it carries no
`as_of_snapshot_id`.

## One statement by its identity

Where `/v1/edgar` puts the company in the path, these routes take the full
identity tuple as parameters. `statement_type`, `fiscal_year` and
`fiscal_period` are required, with `cik` or `ticker` naming the company:

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/normalized-statements?ticker=AAPL&statement_type=INCOME_STATEMENT&fiscal_year=2024&fiscal_period=FY&include_version_history=true" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

The response is the latest version for that identity, and
`include_version_history=true` adds the versions behind it.

For the same statement with its data-quality overlay, name the version as well.
`statement_version_id` is required here, because an overlay describes one
version rather than an identity. Read it from the statement above, where each
version carries its own id:

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/normalized-statements/dq-overlay?ticker=AAPL&statement_type=INCOME_STATEMENT&fiscal_year=2024&fiscal_period=FY&statement_version_id={statement_version_id}" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

## Restatement delta

Compare two versions of one statement and read the per-metric changes, each with
its old value, new value and difference.

Name the two versions with exactly one selector pair, either two accessions or
two statement version ids:

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/restatement-delta?ticker=AAPL&statement_type=BALANCE_SHEET&fiscal_year=2024&fiscal_period=FY&from_accession={from_accession}&to_accession={to_accession}" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

Add `metrics` to narrow the comparison to the metrics you model on. Mixing the
two selector pairs is a caller error rather than a preference, so send one pair.

## Inflation-adjusted series

One company, one metric, returned in both nominal and CPI-adjusted terms:

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/companies/0000320193/metrics/REVENUE/time-series/real?base_year=2024&fiscal_year_from=2015&fiscal_year_to=2024" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

`base_year` sets the currency year the real series is expressed in, and
`cpi_series` chooses which approved CPI series does the deflating.

> **Note:** The projection is computed on read. Normalized statements are never
> rewritten into real terms, so the nominal figures stay exactly what the
> filer reported.

## Macro context

Macro series are here for context around a company's figures, not as a
macroeconomic data service. Only registered series are served, and an arbitrary
FRED code is not accepted.

Read the registry first to see what is approved:

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/macro/series" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

Then read one series over a bounded span. `from_date` and `to_date` are both
required, so a request always says what window it means:

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/macro/series/CPIAUCSL?from_date=2015-01-01&to_date=2024-12-31" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

For a snapshot of the whole approved set around one date, ask for the context:

```bash
curl -X GET "https://api.arche.fi/v1/fundamentals/macro/context/2024-09-28" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

Both reads take `as_of_date`, which applies the same no-lookahead boundary the
rest of the API uses: a revised statistic is read as it stood on that date
rather than as it stands today. The registry itself takes no parameters, since
what is approved does not depend on a date.

## Next steps

- [Company identity](https://docs.arche.fi/identity): Resolve tickers to full issuer records, search by name, and read mapping validity.
- [Time series](https://docs.arche.fi/time-series): Pull a metric across a whole reporting history, point-in-time or as-reported.
- [Metric catalog](https://docs.arche.fi/metrics): Look up canonical and derived metric names, formulas, bundles and segments.