Digests, theses, and themes

Digests and theses are machine-generated analysis written from the article collection; themes group the entities the articles mention together. Each answer cites its evidence.

Routes

route	what it serves
GET /v1/digests/market?date=2026-09-25	the market digest for a day
GET /v1/securities/{symbol}/digest	one security's digest
GET /v1/digests/{ref}	exactly the digest a ref names
GET /v1/securities/{symbol}/thesis	one security's current thesis
GET /v1/theses	the securities with a thesis: each symbol and the thesis' generated_at
GET /v1/themes	a weekly snapshot of groups of entities the articles mention together

Every parameter and response schema is in the API reference.

curl "https://api.tauric.ai/v1/digests/market?date=2026-09-25" \
  -H "Authorization: Bearer $TAURIC_API_KEY"
curl "https://api.tauric.ai/v1/securities/AAPL/thesis" \
  -H "Authorization: Bearer $TAURIC_API_KEY"

Machine-generated analysis

Every /v1/digests/market, /v1/securities/{symbol}/digest, and /v1/securities/{symbol}/thesis answer carries authorship: machine_generated: a language model wrote it from the cited evidence; read it as analysis.

Identity and point in time

A digest's ref is fixed when the digest is written and never changes: every read of that digest returns the same ref. A day's digest written again is a new digest with a new ref, and its supersedes names the ref it replaced. ?date= and the latest read answer the newest digest of the day; GET /v1/digests/{ref} answers exactly that digest, withheld whole if it was withdrawn since. An unknown ref is 404 not_found.

A thesis carries generated_at, when it was written, and revision, a fingerprint of the content as served (null when the content is withheld). The same thesis has the same revision wherever it appears, in a research report included. GET /v1/theses lists generated_at only; read revision on the thesis itself.

?known_at= on the thesis answers the thesis written latest at or before that instant, its evidence checked as it stands now (a withdrawn thesis is withheld). On /v1/themes it answers the snapshot of that instant. The instant must carry a time zone and not lie in the future (otherwise 422 invalid_request); an instant before the first thesis, or the first theme snapshot, is 404 not_found. Both answers state the known_at they answer (null for a read of the latest).

Evidence

Each claim cites its evidence:

• a digest claim's article_ids;
• a thesis claim's article_ids and digest_refs, each {digest, item}: the digest's ref and the 0-based position of the cited item in that digest's content.bullets;
• the thesis' evidence: digests, the refs of the digests it was written from, and cutoff, the instant up to which evidence was considered.

When no cutoff is held, the thesis serves its digests with cutoff: null and says why in field_states (evidence.cutoff).

Withheld content

When any cited evidence is gone, changed, or withdrawn, content is null and withheld gives the reason. A thesis' evidence is still served.

withheld.missing names the evidence that is no longer servable:

entry	the cited evidence
articles_absent	articles that are not held (ids)
articles_withdrawn	articles that were withdrawn (ids)
articles_revised	articles that changed after they were cited (ids)
digests_absent_count	how many cited digests are not held (a digest no longer held has no ref to name)
digests_invalid	digests that are themselves not servable (refs)

withheld.missing is null when the reason names no evidence (document_invalid, document_unavailable, content_withdrawn; see reason codes).

Withdrawn digests and theses

A digest or thesis found materially wrong is withdrawn. ?date=, ?known_at=, or its ref still answers it, withheld whole with content_withdrawn, and the latest is the newest one not withdrawn. A thesis that cites a withdrawn digest is withheld (document_invalid, with the digest in digests_invalid).

Thesis catalysts

Each thesis catalyst carries timing_status, judged against the day (UTC) the thesis was written: past, same_day or upcoming from its date (YYYY-MM-DD), or undated when the evidence fixed no day (its date is then null).

Instruments in digests and theses

Each claim (a digest's bullets and top_stories, a thesis' drivers and risks) carries instruments and unresolved_instrument_count by the same rule as an article's instruments. The content's instruments lists every key the document references.

A thesis' own instrument is the security it is about, the same instrument object every security route answers (its key, such as security:AAPL), stated whether or not a claim's text names it.

The keys of an older document are resolved at the read against the current instrument identities, not those of the document's day.

Themes

A snapshot carries generated_at, when it was computed, and window_days, the trailing window of articles it covers. Each theme's size counts every entity in it. Its members list its most-mentioned entities, at most 50, by mentions descending. A list shorter than size is partial and says so in field_states.members (top_members_only).