Indexes API

Overview

An index is a single number that means something, tracked over time. SentiSense publishes several, each blending its own inputs into one scalar on a stated scale, and all of them answer on the same envelope: one value, an asOf date, the scale it lives on, and where available the breakdown that produced it. Write one renderer and you get every current and future SentiSense index.

Currently live indexes:

Index id	Scale	accessTier	What it measures
market-mood	PERCENT_0_100	free	Proprietary fear-and-greed composite blending social sentiment, market direction, risk appetite, social momentum, S&P 500 trend, and options flow
fed-sentiment	SENTIMENT	free	Weekly weighted sentiment across Federal Reserve leadership and the institution itself, with role-anchored weights that survive a Chair transition
ai-sentiment	SENTIMENT	free	Daily sentiment across AI-exposed names, spanning compute and infrastructure through the AI-native companies

The discovery endpoint is the source of truth for what is live. More indexes ship over time.

Two archetypes, one envelope. Most indexes here are baskets: a weighted average across a curated set of tracked entities. For those, constituents, basketSize, coverage, and totalMentions describe exactly how the headline was built, so you can audit it or discount a low-coverage day. Market Mood is a composite instead, built from six market and social signals rather than a set of entities, so those four fields are null on it. That null is the answer, not a gap: it means the index has no constituents by construction. Branch on it rather than treating it as missing data.

Access: send your API key on every call. Each index declares an accessTier of "free" or "pro" in the discovery listing. Every index is "free" today, which means no response on this page is tier-branched: FREE and PRO callers receive identical payloads. Requests still count against your monthly quota and your per-minute rate limit. Read accessTier from the listing rather than assuming, so a future pro index does not surprise your client.

Scales: SENTIMENT is signed polarity in [-1, +1], where negative is bearish tone and positive is bullish. PERCENT_0_100 is a 0-100 composite where higher is greedier. Read the scale field and set your axis bounds and color bands from it; do not infer them from the index id.

---

GET /api/v1/indexes

Discovery endpoint. Returns every index the platform publishes, with the metadata you need to build a hub, a navigation menu, or a typed client.

Parameters: none.

Example response:

{
  "indexes": [
    {
      "indexId": "fed-sentiment",
      "displayName": "Fed Sentiment",
      "description": "Weekly weighted composite sentiment across Fed leadership and the Federal Reserve institution.",
      "scale": "SENTIMENT",
      "accessTier": "free",
      "canonicalUrl": "/api/v1/indexes/fed-sentiment"
    },
    {
      "indexId": "market-mood",
      "displayName": "Market Mood",
      "description": "SentiSense proprietary 0-100 composite blending social sentiment, market direction, volatility, and momentum.",
      "scale": "PERCENT_0_100",
      "accessTier": "free",
      "canonicalUrl": "/api/v2/market-mood"
    }
  ]
}

Response fields:

Field	Type	Description
indexId	string	URL slug. Use it as the {indexId} path parameter below
displayName	string	Human-readable name, suitable for a card title
description	string	One sentence; suitable for a card subtitle
scale	string	"SENTIMENT" (signed, [-1, +1]) or "PERCENT_0_100"
accessTier	string	"free" or "pro". Every index is "free" today
canonicalUrl	string	Where the richest view of this index lives. See the note below

On canonicalUrl: for most indexes this is simply /api/v1/indexes/{indexId}, the detail endpoint documented next. Market Mood is the exception: it points at /api/v2/market-mood, which carries a phase label, a weekly change, the six-signal breakdown, and an 11-sector map that the shared index envelope has no room for.

That is a pointer to a richer view, not a redirect around a missing one. Every id this endpoint advertises also resolves at /api/v1/indexes/{indexId} and /api/v1/indexes/{indexId}/history, so a generic client can iterate the listing without special-casing anything. Follow canonicalUrl when you want everything an index has; use the detail endpoint when you want every index to answer the same shape.

---

GET /api/v1/indexes/{indexId}

Latest reading for one index. For basket indexes the constituent breakdown is recomputed per request, so you can see which entities contributed and how fresh each reading was.

Parameters:

Parameter	Type	Required	Description
indexId	string	Yes	Index slug from the discovery listing (path parameter)

Example response (a basket index):

{
  "indexId": "fed-sentiment",
  "displayName": "Fed Sentiment",
  "asOf": "2026-06-01",
  "value": 0.12,
  "scale": "SENTIMENT",
  "coverage": 3,
  "basketSize": 3,
  "totalMentions": 480,
  "methodologyNote": "Weekly composite of per-entity mean sentiment over each Monday-Sunday bucket...",
  "constituents": [
    {
      "kbEntityId": "kb/person/618",
      "displayName": "Example Person",
      "role": "Chair",
      "weight": 3.0,
      "value": 0.15,
      "mentionsCount": 260,
      "staleness": "FRESH",
      "contribution": 0.098,
      "link": "https://sentisense.ai/entities/example-person"
    }
  ]
}

Response fields:

Field	Type	Description
indexId	string	Index slug
displayName	string	Human-readable name
asOf	string	Date the reading covers, YYYY-MM-DD. For weekly indexes this is the start of the bucket
value	number	The headline scalar, on scale
scale	string	"SENTIMENT" or "PERCENT_0_100"
coverage	integer	Constituents that actually contributed. null on composite indexes
basketSize	integer	Constituents in the basket on this date. null on composite indexes
totalMentions	integer	Mentions behind the reading. null on composite indexes
methodologyNote	string	How the value was computed, and what any null fields mean
constituents	array	Per-entity breakdown. null on composite indexes

Constituent fields:

Field	Type	Description
kbEntityId	string	Ontology entity id. Resolvable via the Entities API
displayName	string	Entity name
role	string	The entity's role in this basket, which is what carries the weight
weight	number	Relative weight on this date
value	number	The entity's own reading
mentionsCount	integer	Mentions behind that reading in the lookback window
staleness	string	FRESH, CARRIED_FORWARD, EXCLUDED, or OUT_OF_SEGMENT. See below
contribution	number	Reserved. Currently returns null on every constituent; see the note below before using it
link	string	Detail page for the entity, or null when there is no resolvable target

contribution is not populated yet. It is reserved for this entity's share of the headline
value, and it serves null on every constituent today. Do not build on it. You can derive the
same number client-side from fields that are populated: for a weighted-average index, a
constituent's share of the headline is weight * value divided by the sum of weight across the
constituents whose staleness is not EXCLUDED.

Reading staleness: FRESH means the entity was mentioned inside the lookback window. CARRIED_FORWARD means it was not, so its last known reading is standing in. EXCLUDED means it is in the basket but has no usable reading at all and was renormalized out. OUT_OF_SEGMENT means it is not in the basket on this date, which is how the API reports an entity before it took the role that gives it weight; its weight will be 0 and the row is present only for transparency. A day where most constituents are CARRIED_FORWARD is a thin day, and coverage is the fast way to spot one.

Weights are anchored to roles, not to people. When the occupant of a weighted role changes, the weight moves with the role on the transition date. That keeps the series continuous instead of putting a step change in the chart on the day of a handover.

---

GET /api/v1/indexes/{indexId}/history

Historical scalar series for one index, for charting. Returns the stored series, so this is a read rather than a recomputation.

Parameters:

Parameter	Type	Required	Default	Description
indexId	string	Yes		Index slug from the discovery listing (path parameter)
days	int	No	180	Days of history to return

Example response:

{
  "indexId": "fed-sentiment",
  "displayName": "Fed Sentiment",
  "scale": "SENTIMENT",
  "days": 180,
  "history": [
    { "date": "2026-05-18", "value": 0.08 },
    { "date": "2026-05-25", "value": 0.12 }
  ]
}

Response fields:

Field	Type	Description
indexId	string	Index slug
displayName	string	Human-readable name
scale	string	"SENTIMENT" or "PERCENT_0_100"
days	integer	The window you requested, echoed back
history	array	Points of { date, value }, oldest first

Point spacing follows the index, not the calendar. A weekly index returns one point per Monday-Sunday bucket; a daily index returns one point per day. Market Mood returns trading days only, since the market half of the composite is frozen over a weekend while the social half drifts, which would otherwise put a weekend wobble in the line. Plot against the date field rather than assuming a fixed interval.

Thin buckets are withheld. An index may suppress an early-life or low-coverage bucket rather than publish a number it cannot defend, so history can be shorter than the requested window and can contain gaps. Treat missing dates as absent, not as zero.