# MarketSchema — Full API Reference for Agents

> The complete public endpoint map with parameters, response schemas, and
> real production-captured example responses. The short orientation file is
> /llms.txt. OpenAPI: https://api.marketschema.com/openapi.json

Base URL: https://api.marketschema.com
Contract version: 3.0.0
Public endpoints: 14 (plus the /health utility, documented below)
Auth: free API key (1 key, daily quotas) — create at https://marketschema.com/account
MCP (hosted): https://marketschema-mcp-production.up.railway.app/mcp (streamable HTTP)
OpenAI tools manifest: https://api.marketschema.com/v1/agent/openai-tools

Reading a Schema Score: 0-100, a cross-sectional rank vs board peers.
Every score payload carries as_of + freshness — always check them; the
honesty fields are part of the contract, not decoration. Every index
publishes its exact formula (weights, components, normalization) on its
page and via GET /indices/{symbol}.

## Provenance & honesty fields

Every asset packet (GET /v1/asset/{ticker} → asset) carries
machine-consumable provenance. Field meanings:

- as_of (ISO-8601): when the underlying data the score was computed from
  was current. THE staleness check — compare against now, not computed_at.
- computed_at (ISO-8601): when this packet was materialized. computed_at
  can be recent while as_of is old; trust as_of.
- freshness (string): live | current | delayed | stale | missing — the
  packet-level freshness verdict. Treat anything past "current" as a
  reason to lower confidence in downstream decisions.
- freshness_chain (object): per-input freshness, keyed by index symbol
  (e.g. {"CRSI": "live"}). Lets an agent see WHICH input is dragging.
- confidence (number 0-100): the platform's own confidence in this score.
- score_version (integer): scoring methodology version; bump = the number
  is not comparable with packets from older versions.
- component_weights (object): the live sleeve weights this score actually
  used after missing-sleeve redistribution (fundamentals_component /
  macro_signal / entry_value / narrative_component, fractions summing to
  1). May be empty on packets written before the field existed.
- data_source (string): which store served this packet (asset_packets =
  materialized canonical; live_compute = computed on demand for coverage).
- changed_since_last (array): driver-level changes vs the previous packet.

Index payloads (GET /indices/{symbol}) publish the full formula:
components with series ids, sources, weights, and the methodology
version — the same numbers rendered in the "How It's Calculated" box on
every index page. Nothing is withheld; verify the math yourself.

## Market Data

The five primitives: schema scores, risk scores, indexes, narratives, themes. Live routes, promoted to the public contract.

### GET /v1/gauges

Risk Gauges. Market-wide risk gauges by family (liquidity, credit, volatility…) computed from the published indexes.

Auth: none (public)

Response fields:
- gauges (array): Per-family gauge rows: gauge_key, label, value, signal, members
- computed_at (datetime): When the gauges were computed

Example response (captured from production):
```json
{
  "gauges": [
    {
      "gauge_key": "liquidity",
      "label": "Liquidity & Stress",
      "value": -0.05847155555555556,
      "signal": "neutral"
    },
    {
      "gauge_key": "credit",
      "label": "Credit",
      "value": -0.05265661111111112,
      "signal": "neutral"
    },
    {
      "gauge_key": "rates",
      "label": "Rates & Curve",
      "value": -0.005137444444444442,
      "signal": "neutral"
    }
  ],
  "computed_at": "2026-06-12T11:42:43.596255+00:00"
}
```

### GET /api/market-risk/current

Market Risk Composite. The home-page composite: risk, volatility, and liquidity scores with freshness metadata.

Auth: none (public)

Response fields:
- risk_score (int): 0–100 market risk composite
- volatility_score (int): 0–100 volatility gauge
- liquidity_score (int): 0–100 liquidity gauge
- freshness (object): status + as_of for the read

Example response (captured from production):
```json
{
  "risk_score": 51,
  "volatility_score": 41,
  "liquidity_score": 53,
  "freshness": { "status": "live" }
}
```

### GET /indices

List Indexes. All published macro indexes with current values. Every formula published on its index page.

Auth: none (public)

Response fields:
- symbol (string): Index symbol (e.g. CRSI)
- name (string): Full index name
- current_value (float): Latest computed value (σ units)

Example response (captured from production):
```json
[
  {
    "symbol": "ACSI",
    "name": "AI Compute Capex Index",
    "current_value": 0.138589
  },
  {
    "symbol": "ALVI",
    "name": "Auto Lending Volume Index",
    "current_value": -1.272806
  },
  {
    "symbol": "ASPI",
    "name": "AI Buildout Bottleneck Index",
    "current_value": -0.271455
  }
]
```

### GET /indices/{symbol}/history

Index History. Time series of values for one index.

Auth: none (public)

Path parameters:
- symbol: Index symbol (e.g. CRSI)

Response fields:
- points (array): Timestamped index values

Example response (captured from production):
```json
{
  "symbol": "CRSI",
  "points": [ { "t": "2026-06-11", "value": 0.6326 } ]
}
```

### GET /v1/trust/narrative-graph

Narrative Graph. All tracked market narratives with momentum, state, and coverage — what the market is trading on.

Auth: none (public)

Response fields:
- narrative_count (int): Number of tracked narratives
- narratives (array): slug, label, state, momentum windows, coverage

Example response (captured from production):
```json
{
  "narrative_count": 33,
  "items": [
    {
      "slug": "war-oil-shock",
      "label": "War / Oil Shock",
      "state": "Dormant",
      "momentum_1w": 11.0
    },
    {
      "slug": "ai-infrastructure-buildout",
      "label": "AI Infrastructure Buildout",
      "state": "Weakening",
      "momentum_1w": -10.0
    },
    {
      "slug": "power-bottleneck",
      "label": "Power Bottleneck",
      "state": "Dormant",
      "momentum_1w": -14.0
    }
  ]
}
```

### GET /api/assets/{asset_id}

Asset Detail (Themes). Full asset detail including related_themes: per-asset theme exposure with direction and impact.

Auth: none (public)

Path parameters:
- asset_id: class:ticker form (e.g. equity:NVDA)

Response fields:
- asset (object): Detail packet (price, score, profile)
- asset.related_themes (array): slug, name, score, direction, impact

Example response (captured from production):
```json
{
  "ticker": "NVDA",
  "related_themes": [
    {
      "slug": "semiconductor-supercycle",
      "name": "Semiconductor Supercycle",
      "score": 57,
      "direction": "tailwind",
      "impact": 0.0756
    },
    {
      "slug": "data-center-thermal-bottleneck",
      "name": "Data Center Thermal Bottleneck",
      "score": 74,
      "direction": "tailwind",
      "impact": 0.0756
    }
  ]
}
```

## Agents & Streaming

The agent-native surface: OpenAI tool manifests and the live SSE stream. MCP server config lives on /developers.

### GET /v1/agent/openai-tools

OpenAI Tools Manifest. Function-calling schemas for OpenAI-compatible agents — 6 tools covering regime, trade checks, indexes, signals, pulse, and decision packets. No auth required.

Auth: none (public)

Response fields:
- tools (array): OpenAI function schemas (type, function.name, function.parameters)

Example response (captured from production):
```json
{
  "tools": [
    { "type": "function", "function": { "name": "get_market_regime", "description": "Get the current MarketSchema macro regime." } },
    { "type": "function", "function": { "name": "check_trade", "description": "Check a ticker against the current deterministic MarketSchema read." } }
  ],
  "count": 6
}
```

### GET /v1/stream

Live SSE Stream. Server-sent events: index snapshots, conditions, and ticker-tape updates. channels query param selects feeds (indices, conditions, ticker_tape, market_status).

Auth: none (public)

Response fields:
- event (string): SSE event name (snapshot, update)
- data (object): channel, event_type, timestamp, payload

Example response (captured from production):
```json
event: snapshot
data: {"channel":"marketschema:stream:indices","event_type":"snapshot","timestamp":"2026-06-12T12:54:21Z","data":{"indices":[{"symbol":"ACSI","value":0.138589,"signal":"neutral","computed_at":"2026-06-12T12:53:01Z"}]}}
```

## Public API

The canonical public contract. Get asset packets, subscribe to updates, verify identity.

### GET /v1/asset/{ticker}

Get Asset Packet. Canonical Schema Score packet for a single asset. Returns score, state, confidence, freshness, price, and drivers.

Auth: X-API-Key header required

Path parameters:
- ticker: Asset symbol (e.g. AAPL)

Response fields:
- ticker (string): Asset symbol
- asset_class (string): equity, crypto, commodity, real_estate, rates_fx
- schema_score (int | null): 0–100 composite structural score
- schema_state (string): Qualitative band: strong_tailwind, tailwind, mixed, headwind, strong_headwind
- confidence (float): 0.0–1.0 score confidence
- freshness (string): live, stale, or degraded
- as_of (datetime): When the score was last computed
- price (float): Latest price
- price_change_1d (float): 1-day price change ratio
- price_change_7d (float): 7-day price change ratio
- score_delta_1d (int): Score point change (1 day)
- score_delta_7d (int): Score point change (7 days)
- top_drivers (array): Top index drivers with weight and direction

Example response (captured from production):
```json
{
  "ticker": "AAPL",
  "asset_class": "equity",
  "schema_score": 72,
  "schema_state": "tailwind",
  "confidence": 0.88,
  "freshness": "live",
  "as_of": "2026-03-31T14:30:00Z",
  "price": 234.50,
  "price_change_1d": 0.012,
  "price_change_7d": -0.008,
  "score_delta_1d": 3,
  "score_delta_7d": -2,
  "top_drivers": [
    { "index": "MS-LIQUIDITY", "weight": 0.18, "direction": "pro" },
    { "index": "MS-CREDIT-STRESS", "weight": 0.14, "direction": "anti" }
  ]
}
```

### POST /v1/check/batch

Batch Asset Packets. Evaluate up to 25 tickers in one call. Returns canonical Schema Score packet per ticker plus shared market context.

Auth: X-API-Key header required

Request body fields:
- tickers (string[], required): Array of ticker symbols (max 25)
- direction (string, optional): Score orientation: long or short (default: long)

Response fields:
- decisions (array): Array of canonical asset packets
- market_context (object): Shared regime, gate state, and timestamp

Example response (captured from production):
```json
{
  "decisions": [
    { "ticker": "AAPL", "schema_score": 72, "schema_state": "tailwind", "confidence": 0.88 },
    { "ticker": "NVDA", "schema_score": 81, "schema_state": "strong_tailwind", "confidence": 0.92 }
  ],
  "market_context": {
    "regime": "risk_on",
    "gate_open": true,
    "as_of": "2026-03-31T14:30:00Z"
  }
}
```

### GET /v1/bot/auth/whoami

Verify API Key. Verify your API key and return bot identity, plan tier, and entitlements.

Auth: X-API-Key header required

Response fields:
- bot_id (string): Your bot identifier
- plan (string): Plan tier: free, pro, elite
- entitlements (object): Quota limits and feature flags

Example response (captured from production):
```json
{
  "bot_id": "acme-momentum-bot",
  "plan": "pro",
  "entitlements": {
    "daily_quota": 5000,
    "batch_size": 25,
    "stream": true,
    "webhooks": 5
  }
}
```

### GET /v1/bot/auth/capabilities

Bot Capabilities. Machine-readable capability surface and quotas for your API key.

Auth: X-API-Key header required

Response fields:
- endpoints (array): Available endpoints for your plan
- rate_limits (object): Current rate limit state
- features (object): Feature flags (stream, webhooks, batch)

Example response (captured from production):
```json
{
  "endpoints": ["/v1/asset/{ticker}", "/v1/check/batch", "/v1/alerts/stream", "/v1/webhooks/*"],
  "rate_limits": { "daily_quota": 5000, "remaining": 4872, "resets_at": "2026-04-01T00:00:00Z" },
  "features": { "stream": true, "webhooks": true, "batch_size": 25 }
}
```

### POST /v1/bot/auth/stream-token

Get Stream Token. Request a temporary token to subscribe to authenticated streaming channels. Token expires after 1 hour.

Auth: X-API-Key header required

Response fields:
- token (string): Bearer token for WebSocket or SSE authentication
- expires_at (datetime): Token expiration time (ISO-8601)
- channels (array): Authorized streaming channels

Example response (captured from production):
```json
{
  "token": "st_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-03-31T15:30:00Z",
  "channels": ["bot_alerts", "bot_conditions"]
}
```

### GET /v1/alerts/stream

Score Updates Stream (SSE). Server-Sent Events stream of score update events. Requires stream token from /v1/bot/auth/stream-token.

Auth: X-API-Key header required

Response fields:
- event (string): Event type: score_update, state_change
- data (object): Canonical asset packet

Example response (captured from production):
```json
event: score_update
data: {"ticker":"AAPL","schema_score":73,"schema_state":"tailwind","as_of":"2026-03-31T14:31:00Z"}
```

## Health

API health check. Good first call to verify connectivity.

### GET /health

Health Check. Returns API status, version, and component health (Redis, database).

Auth: none (public)

Response fields:
- status (string): 'healthy' or 'degraded'
- version (string): API version
- environment (string): 'production', 'staging', etc.
- checks (object): { api, redis, database } — each 'ok', 'unavailable', or 'error'

Example response (captured from production):
```json
{
  "status": "healthy",
  "version": "0.1.0",
  "environment": "production",
  "checks": { "api": "ok", "redis": "ok", "database": "ok" }
}
```