API documentation

A read-only JSON API. Every endpoint lives under https://api.atomicresearch.markets/v1.

Authentication

Send your key as a bearer token on every request. Keys are issued by email when you subscribe.

curl -H "Authorization: Bearer ark_your_key_here" \
  https://api.atomicresearch.markets/v1/symbols/AAPL

We store only a hash of your key, so we cannot recover it if you lose it. Write to help@atomicresearch.markets and we will issue a replacement.

Endpoints

Endpoint	Returns
`GET /v1/symbols/{symbol}`	Every signal your plan covers for one company
`GET /v1/symbols/{symbol}/{signal_id}`	A single signal for one company
`GET /v1/catalog`	All 56 signal definitions. No key required
`GET /v1/plans`	Plan coverage and limits. No key required
`GET /v1/bulk/latest`	A time-limited link to the full daily snapshot. Full plan only
`GET /v1/health`	Service status. No key required

The response

A request for one company returns its observations for the most recent snapshot.

{
  "symbol": "AAPL",
  "snapshot_date": "2026-08-18",
  "plan": "broad",
  "atom_count": 56,
  "atoms": [
    {
      "signal_id":          "cash-flow.fcf-trend-and-stability",
      "family":             "Cash Flow Evaluation",
      "state":              "neutral",
      "value":              0,
      "definition_version": 1,
      "maturity":           "deterministic",
      "method":             "cagr=-3.95%;years=3;latest-vs-avg=0.9438",
      "evidence_date":      "2025-09-30",
      "period":             "FY2025",
      "observed_at":        "2026-08-14T15:58:00.985Z"
    }
  ]
}

Field reference

state

The answer to the question. The three absence states are distinct on purpose, because "we could not tell" is different information from "the answer is no".

`positive`	Evidence supports the question, `value` is `1`
`neutral`	Evidence is mixed or unremarkable, `value` is `0`
`negative`	Evidence runs against the question, `value` is `-1`
`missing`	The inputs were not available
`inapplicable`	The question does not apply to this company
`failed`	The computation was attempted and did not complete
`not-yet-available`	The evidence is expected but has not been published yet

maturity

How the answer was produced. Use this to decide how much weight to give it; you can filter on it entirely if you only want arithmetic.

`deterministic`	Computed from filings. Reproducible from the stated inputs
`structured-extraction`	Read from a document into a fixed schema
`naive-web-search`	Judged from public sources by a language model
`incomplete`	Partially wired. Treat with caution

Signals above deterministic involve a language model and can be wrong. The method field always states the reasoning, so you can check it rather than take it on trust.

Other fields

`evidence_date`	The date the underlying evidence describes
`period`	The fiscal period, such as `FY2025`
`observed_at`	When we produced the observation
`definition_version`	Increments if a signal's meaning ever changes

Errors

Errors return a JSON body with a stable code.

`401`	Key missing, unrecognised, or revoked
`403`	Your plan does not cover that company, signal, or bulk access
`404`	No such company, or no such signal
`429`	Above your plan's request rate

{
  "error": {
    "code": "symbol_not_in_plan",
    "message": "Your Core plan does not cover TSLA.",
    "hint": "See /v1/plans for coverage of each plan."
  }
}

Bulk download

On the Full plan, /v1/bulk/latest returns a signed link to the day's complete snapshot as newline-delimited JSON, one company per line. The link expires after fifteen minutes; request another whenever you need one.

Refresh cadence

A new snapshot is written every morning. Individual signals refresh on their own schedules, because a cash-flow figure only changes when a filing arrives, while other evidence moves more often. Each observation carries its own observed_at and evidence_date, so you always know how fresh it is rather than having to assume.