# Narratives and explanations

These two routes return prose Arche generated about a company: what changed in a
period, and why a data-quality anomaly was raised. Both key off `company_id`, the
UUID, not the CIK. Get one from [`/v1/identity/resolve`](https://docs.arche.fi/identity).

Narratives need the Growth plan, and anomaly explanations need Scale. A plan
without them answers `403 FEATURE_NOT_AVAILABLE`, naming what is required.

## Snapshot first

`as_of` is required on both routes, and it must name an as-of snapshot that
already exists with generated artifacts behind it. A date with no provisioned
snapshot answers `404`, which is the same surprise the [modeling](https://docs.arche.fi/modeling)
routes carry and for the same reason.

So these are not routes to call on an arbitrary date. Call them on a date your
pipeline knows was built.

## Narratives

```bash
curl -X GET "https://api.arche.fi/v1/ai/companies/{company_id}/narratives?as_of={as_of}&narrative_type=CHANGE_SUMMARY&statement_type=INCOME_STATEMENT&page_size=50" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

- `narrative_type` (required): `CHANGE_SUMMARY`, `MARGINS_MOVE` or `ROIC_CHANGE`. Each answers a different
  question, so the parameter selects the narrative rather than filtering a
  list of them.
- `statement_type` (default INCOME_STATEMENT): Which statement the narrative draws its inputs from.

A narrative is generated once and cached, so repeating the request returns the
same text rather than a fresh rewording. That is deliberate: a figure and the
sentence explaining it should not drift apart between two reads.

## Anomaly explanations

```bash
curl -X GET "https://api.arche.fi/v1/ai/companies/{company_id}/anomaly-explanations?as_of={as_of}&min_severity=HIGH&page_size=50" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

- `min_severity` (optional): `NONE`, `LOW`, `MEDIUM`, `HIGH` or `CRITICAL`. Filters to explanations at or
  above that materiality.
- `dq_run_id` (optional): Narrow to one data-quality run, when you are reconciling against a specific
  overlay you already read.

These explain anomalies the data-quality rules raised. The anomalies themselves,
without prose, come from
[`/v1/data-quality/issues`](https://docs.arche.fi/coverage#data-quality-issues) and the statement
overlay, and neither of those needs a paid plan or a snapshot.

## What is populated today

Coverage here is narrower than the rest of the corpus, and worth knowing before
you build on it. Narratives exist for a minority of companies and anomaly
explanations for fewer, because both are generated against snapshots rather than
computed on read.

Treat an empty page as "not generated for this company and date" rather than
"nothing to say". The underlying figures are always available from the
[statement](https://docs.arche.fi/time-series) and [data-quality](https://docs.arche.fi/coverage) routes, which cover the
whole corpus.

## 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.
- [Fundamentals](https://docs.arche.fi/fundamentals): Read panels across many companies, name a statement by its identity, and pull the approved macro context.