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.

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

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"

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

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"

These explain anomalies the data-quality rules raised. The anomalies themselves, without prose, come from /v1/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 and data-quality routes, which cover the whole corpus.