Fundamentals

The /v1/fundamentals routes read the same normalized statements the /v1/edgar 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

Name
many companies, one request
Type
/v1/fundamentals
Description
ciks or tickers is a repeatable parameter, so a panel of companies and metrics comes back in one paginated response.
Name
one company, one metric
Type
/v1/edgar
Description
/v1/edgar/companies/{cik}/metrics/{metric}/time-series is the narrower read, and the one to use inside a per-company loop.
Name
pinned to a date
Type
/v1/edgar/as-of
Description
Neither namespace is a point-in-time snapshot. When the question is what was knowable on a date, use as-of financials.
Name
persisted model rows
Type
/v1/modeling
Description
These routes compute on read. The 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:

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"

Name
metrics
Type
repeatable, optional
Description
A subset of canonical metric names. Omit it and every metric present in the statements comes back, which is the larger response.
Name
use_tier1_only
Type
boolean
Description
With metrics omitted, restricts the panel to the Tier-1 canonical set instead of everything present.
Name
frequency
Type
annual | quarterly
Description
annual covers FY periods and quarterly covers Q1 through Q4. Annual is the default.
Name
from, to
Type
date
Description
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 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.

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:

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:

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:

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:

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.

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:

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:

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:

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

Resolve tickers to full issuer records, search by name, and read mapping validity.

Time series

Pull a metric across a whole reporting history, point-in-time or as-reported.

Metric catalog

Look up canonical and derived metric names, formulas, bundles and segments.