sentisense

SentiSense API - Skill File for AI Agents

SentiSense is a read-only financial intelligence API: stock prices, insider/politician trading, institutional flows, AI insights, and news sentiment. No trading, no purchases, no write operations. Free tier available.

Base URL: https://app.sentisense.ai Website: https://sentisense.ai ClawHub Skill: clawhub.ai/TheSentiTrader/sentisense API Docs: https://sentisense.ai/docs/api/ Authentication: API key via X-SentiSense-API-Key header. Get a free key at https://app.sentisense.ai/get-api-key SDKs (optional): Python | Node.js -- source on GitHub. As an AI agent, you're encouraged to call the REST API directly with curl/fetch rather than installing packages.

---

Use & Disclaimer

This skill is an educational data interface to SentiSense's read-only Data API. Output is informational only. It is not investment advice, not a personalized recommendation, and not a solicitation to buy or sell any security. The user is responsible for their own decisions. Use of the API and this skill is subject to the API Terms of Service and Terms of Service.

---

Authentication

# Include API key in header
curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/..."

import os
from sentisense import SentiSenseClient
client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])

All API endpoints require an API key. Get one free at https://app.sentisense.ai/get-api-key (manage it anytime in the Developer Console).

Access Tiers

Rate Limits

Ticker Symbols

Endpoints that take a {ticker} path parameter accept the canonical primary ticker for each company. For dual-class share companies, the API also accepts the secondary class as an alias and resolves it server-side, so you can pass whichever ticker your data source provides.

Aliasing applies to research endpoints (analyst, KPIs, insights, insider, institutional holders, politicians filings, options). Quote and chart endpoints leave the ticker as-is, since market-data providers handle their own symbology. Tickers are case-insensitive. News Corp (NWSA/NWS) and Fox (FOXA/FOX) are NOT aliased to each other (each class is tracked separately).

---

What You Can Build

Smart Money Tracker

Cross-reference insider trading, institutional flows, and politician trades to follow where the smart money is moving. High-conviction signals come from convergence across all three.

• GET /api/v1/insider/activity for market-wide insider buying/selling
• GET /api/v1/institutional/flows for quarterly institutional positioning (optional reportDate; omit for the latest quarter)
• GET /api/v1/politicians/activity for congressional STOCK Act trades
• GET /api/v1/insights/stock/{ticker} for AI signals that combine these data sources

Sentiment-Driven Watchlist

Alert when sentiment shifts for your stocks. Track news volume, social mentions, and baseline deviations.

• GET /api/v2/metrics/entity/{ticker}/metric/sentiment for sentiment time series
• GET /api/v2/metrics/entity/{ticker}/baselines/sentiment for anomaly detection (3-sigma deviations)
• GET /api/v1/documents/ticker/{ticker} for the underlying news and social posts driving the shift

Congressional Trade Monitor

Track what Congress is buying before it moves. Filter by party, chamber, or individual politician. Check if corporate insiders agree.

• GET /api/v1/politicians/activity for recent congressional trades across all members
• GET /api/v1/politicians/member/{slug} for individual politician profiles and trade history
• GET /api/v1/insider/trades/{ticker} to cross-reference with corporate insider activity on the same stock

AI Research Assistant

Generate stock research reports by combining multiple data signals into a single analysis.

• GET /api/v1/stocks/{ticker}/ai-summary?depth=deep for the full AI analysis report
• GET /api/v1/insights/stock/{ticker} for AI-generated stock signals
• GET /api/v1/stocks/fundamentals?ticker={ticker} for a single period of financial statement data
• GET /api/v1/stocks/fundamentals/history?ticker={ticker}&timeframe=annual&limit=10 for multi-year revenue, margin, and free-cash-flow trend to support valuation work
• GET /api/v1/documents/ticker/{ticker} for recent news context

Earnings Calendar Monitor

Position ahead of earnings instead of reacting to them. Pull the forward calendar, intersect it with a watchlist, and pre-load sentiment and smart-money context for the companies reporting soon.

• GET /api/v1/calendar/earnings?week=next for who reports next week (or ?from=&to= for a custom window)
• GET /api/v1/calendar/earnings?ticker={ticker} for a single name's next report date and consensus EPS
• GET /api/v2/metrics/entity/{ticker}/metric/sentiment to gauge positioning into the print
• GET /api/v1/insider/trades/{ticker} to see if insiders moved ahead of the date

Market Dashboard

Real-time market overview combining prices, sentiment, and top signals.

• GET /api/v1/stocks/market-status to check if the market is open
• GET /api/v1/market-summary for AI-generated market headline and analysis
• GET /api/v1/insights/market for the top market-moving signals right now
• GET /api/v1/stocks/prices?tickers=SPY,QQQ,IWM,DIA for index tracking

Market Sentiment Structure

Which way the market's tone leans, and how widely it's shared. Daily snapshots.

• GET /api/v1/sentiment/sectors for the 11 GICS sectors vs the market's own tone (consensusVsMarket + "Hotter/Cooler than market" labels; market-relative because news tone skews positive as a genre)
• GET /api/v1/sentiment/breadth for the bullish/neutral/bearish share of ~1,000 covered stocks (the sentiment advance/decline line; netBreadth in points, stock- and mention-weighted)
• GET /api/v1/trackers/sentiment-leaderboard for the most bullish and bearish stocks by pure sentiment polarity (tone, not the SentiSense Score), with a minimum-mention confidence floor
• GET /api/v1/trackers/sentiment-movers for the biggest 7-day shifts in tone, improving and deteriorating

---

Agent Tips

Workflow Pattern

1. Call GET /api/v1/stocks/market-status first to check if the market is open
2. Call GET /api/v1/institutional/quarters before the institutional endpoints that need a reportDate to get valid values (/flows does not need one; omit it for the latest quarter)
3. All PRO-gated endpoints return {isPreview, previewReason, data}. Always access response["data"] (or response.data). On a preview (FREE) list response a totalCount field is also present: the number of items in the full PRO dataset, so you can show "showing N of totalCount"
4. Use lookbackDays (1-365) on insider and politician endpoints to control the time window

Common Mistakes

• Do NOT hardcode reportDate for institutional endpoints. When you pass one, fetch it from /quarters first; quarters change as new SEC filings come in. (/flows does not require one: omit it for the latest quarter, or pass one for a specific quarter.)
• Do NOT iterate the response directly. Unwrap response["data"] first. All PRO-gated endpoints use the {isPreview, previewReason, data} wrapper
• Do NOT use /api/v1/entity-metrics/* for metrics. These are RETIRED (return 410 Gone). Use /api/v2/metrics/ instead
• The source parameter is case-insensitive. news, NEWS, News all work

Endpoints That Do NOT Exist

Do not hallucinate these. They are not part of the SentiSense API:

• /api/v1/options/flow or /api/v1/dark-pool: these exact paths do not exist. For end-of-day options analytics (IV rank, put/call percentile, 25-delta skew, open-interest walls, max pain, unusual-by-volume contracts) use the Options Intelligence endpoints instead: /api/v1/options/overview and /api/v1/stocks/{ticker}/options/summary. We do not attribute tick-level order flow (no buy/sell aggressor tagging) and we have no dark-pool data
• /api/v1/earnings: for the earnings calendar use /api/v1/calendar/earnings; for reported financials use /api/v1/stocks/fundamentals (single period) or /api/v1/stocks/fundamentals/history (multi-period trend, up to 40 quarters or 20 years)
• /api/v1/alerts or /api/v1/notifications: alerts are user-facing only, not available via API
• /api/v1/chat or /api/v1/ask: the AI chat is not accessible via API
• /api/v2/sentiment: the correct path is /api/v2/metrics/entity/{id}/metric/sentiment
• /api/v1/congress or /api/v1/congressional: the correct path is /api/v1/politicians

---

Stocks API (/api/v1/stocks)

GET /api/v1/stocks/price

Real-time stock price. Public.

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/price?ticker=AAPL"

Response: { ticker, currentPrice, change, changePercent, previousClose, volume, timestamp, expiresEpochSecond, extendedHours? }.

currentPrice is always the regular-session price: live last trade during RTH (09:30 to 16:00 ET), most recent regular-session close otherwise. The optional extendedHours field is present only during pre-market (04:00 to 09:30 ET) or after-hours (16:00 to 20:00 ET) and carries { session: "pre" | "post", price, change, changePercent }, where change / changePercent are computed vs currentPrice.

GET /api/v1/stocks/prices

Batch real-time prices. Public. Returns a JSON array; each element has the same shape as /price (including a ticker field and an optional extendedHours object).

GET /api/v1/stocks/chart

Historical OHLCV chart data. Public.

MAX returns a stock's full available history, up to 26 years (AAPL: 320 monthly bars back to 1999). Granularity scales with the range: intraday for 1D through 1M (5-minute for 1D, 15-minute for 5D, 30-minute for 1W, hourly for 1M), daily for 3M through 1Y, weekly for 5Y/10Y, monthly for MAX. Ranges of 10Y and MAX are adjusted for both splits and dividends so the series is comparable end to end; shorter ranges (through 5Y) are split-adjusted only, so the two bases differ on the same historical date by roughly the dividends paid since.

10Y and MAX may answer 202 Accepted with an empty array and a Retry-After header, meaning that stock's deep history is still being assembled; retry and you get the full series. A 200 always carries the range you asked for, never a silently shortened one.

Each bar includes timestamp (Unix ms), date, open, high, low, close, volume, and session. The session field is pre (04:00 to 09:30 ET), regular (09:30 to 16:00 ET), or post (16:00 to 20:00 ET) for intraday timeframes (1D, 5D, 1W, 1M); it is null for daily, weekly, and monthly bars (3M and longer) that span whole sessions. The 1M timeframe is filtered to regular-session bars only.

GET /api/v1/stocks

List all tracked ticker symbols. Public.

GET /api/v1/stocks/detailed

All stocks with company name, KB entity ID, URL slug, and precomputed socialDominance ({ value, rank, percentile }, daily refresh, null when no signal). Public.

Example: sort the universe by share of voice without any second request, or filter by socialDominance.rank <= 50 for the top-50 most discussed names.

GET /api/v1/stocks/popular

Popular stock tickers. Public.

GET /api/v1/stocks/popular/detailed

Popular stocks with company details (same schema as /detailed). Public.

GET /api/v1/stocks/images

Company logo URLs. Public. GET a returned URL to receive the image bytes; no API key is needed for the image fetch itself. Treat the URLs as refreshable rather than permanent: brand assets are periodically refreshed, so re-read them from this endpoint instead of storing them long term.

GET /api/v1/stocks/descriptions

Company profiles with branding, industry, and market cap; sector when available (often absent). Public.

GET /api/v1/stocks/{ticker}/profile

Company profile (CEO, sector, industry). Public.

GET /api/v1/stocks/{ticker}/similar

Peer/similar stocks. Public.

GET /api/v1/stocks/{ticker}/sentiment

One-call sentiment picture for a stock: the SentiSense Score with its 30-day regime, where the conversation is happening by source, and what is driving it. Free (API key required).

Returns ticker, companyName, asOf, then:

Use this when you want the headline read in one call. Use GET /api/v2/metrics/entity/{ticker}/metric/sentiment instead when you need a time series over a specific window. Returns 404 when the ticker has no sentiment coverage.

Via the MCP connector this same picture comes back from the get_stock_snapshot tool rather than a separate sentiment tool.

GET /api/v1/stocks/{ticker}/entities

Related ontology entities (CEO, products, partners). Public. Each entry carries a urlSlug (e.g. Tim-Cook) that plugs into the Metrics API {entityId} parameter.

GET /api/v1/stocks/{ticker}/ai-summary

AI-generated stock analysis report. PRO (Free: depth=basic unlimited, depth=deep limited to 10/month). depth=basic returns a preheader summary. depth=deep returns a full multi-section report. Exhausting the depth=deep monthly view allowance returns 429 with {error: "quota_exceeded", ...}, the same contract as every other quota-gated endpoint.

Response: flat object (no {isPreview, data} wrapper).

GET /api/v1/stocks/{ticker}/metrics/{metricType}/breakdown

Sentiment or mention metrics breakdown by sub-entities. Public.

GET /api/v1/stocks/market-status

Current market open/closed status. API key required.

Response: { status: "open" | "closed", timestamp: }. The timestamp is a numeric epoch milliseconds value (not a string).

GET /api/v1/stocks/fundamentals

Financial statement data. Public.

Reporting currency (applies to every fundamentals endpoint): figures are as reported by the filer, in the filer's own currency, never converted to USD. Foreign ADR filers report in home currency (SK hynix: KRW, Toyota: JPY, ASML: EUR). The optional reportedCurrency field ("USD", "KRW", ...) on the response (and on each /fundamentals/history row) names it; when absent the currency is unknown, not implicitly USD. Never mix these figures with the share price: the price is the USD ADR price, so for non-USD filers peRatio / psRatio / pbRatio are served as null on purpose, and you should not recompute them. Same-currency ratios (margins, ROE, ROA, current ratio, debt/equity) stay valid for all filers.

GET /api/v1/stocks/fundamentals/current

Most recent fundamental data snapshot. Public.

GET /api/v1/stocks/fundamentals/history

Multi-period history of full financial statements (income statement, balance sheet, cash flow), one entry per fiscal quarter or year, newest first. Use for margin trends, multi-year comparisons, or as the input to a valuation model. Not the same endpoint as /fundamentals (single period) or /fundamentals/historical/revenue (income-statement lines only, no balance sheet or cash flow). Public.

Response includes count (periods actually returned, can be less than limit), reason (non-null only when periods is empty, e.g. a recent listing), and dataSource (deprecated: always an empty string, kept for response-shape compatibility, slated for removal).

GET /api/v1/stocks/fundamentals/periods

Available fiscal periods. Public.

GET /api/v1/stocks/fundamentals/historical/revenue

Historical income-statement lines per period: revenue, gross profit, operating income, net income, and EPS. Response wraps them in dataPoints (not periods like /fundamentals/history), plus count, dataSource, and reason. For full statements including balance sheet and cash flow, use /fundamentals/history instead. Public.

GET /api/v1/stocks/short-interest

Short interest data from FINRA. Public.

GET /api/v1/stocks/float

Float information (shares outstanding, public float). Public.

GET /api/v1/stocks/short-volume

Short volume trading data. Public.

GET /api/v1/stocks/{ticker}/quote

Aggregate quote snapshot: live price, today OHLC, 52-week range, market cap, P/E, EPS TTM, dividend yield, 200-day moving average. Single call for detail pages. API key required.

Response: { ticker, currentPrice, change, changePercent, volume, open, dayHigh, dayLow, previousClose, week52High, week52Low, marketCap, peRatio, epsTTM, dividendYield, movingAverage200Day, reportedCurrency, timestamp, extendedHours? } -- all fields except ticker are nullable. currentPrice is always the regular-session price; the optional extendedHours object ({ session, price, change, changePercent }) is present only during pre-market or after-hours. movingAverage200Day is null when fewer than 200 trading days of history exist. reportedCurrency ("USD", "EUR", "KRW", ...) names the currency epsTTM is reported in, matching the fundamentals endpoints. Cached 15 s server-side.

Null fields are omitted, and foreign filers omit the fundamentals trio. A null field is left out of the JSON entirely rather than serialized as null, so do not assume a key is present: read defensively. In particular reportedCurrency, epsTTM and peRatio are all absent on foreign ADR filers such as ASML and TM, while price fields and dividendYield are served normally. This is the same cross-currency rule as the fundamentals endpoints: the price is the USD ADR price and the filer's earnings are in home currency, so peRatio is withheld rather than computed across two currencies. Do not divide currentPrice by a non-USD epsTTM to fill the gap yourself.

ETF tickers (e.g. VTI, SPY) return 400 ticker_is_etf from this endpoint. Use GET /api/v1/etfs/{ticker}/quote instead, which returns AUM, expense ratio, NAV, and inception date rather than market cap, P/E, and EPS.

GET /api/v1/stocks/{ticker}/kpis

Company-specific KPI time-series. Curated GAAP and non-GAAP metrics from earnings filings: iPhone unit sales, Tesla deliveries, AWS revenue, Netflix paid net adds, etc. PRO (preview) -- Free: metadata only with empty kpis list, PRO: full series. Returns 404 for tickers without curated coverage.

Coverage today: near-complete for the S&P 500 plus extended universe (~500 tickers). Use GET /api/v1/stocks/with-kpis to enumerate.

Response wrapper: { isPreview, previewReason, data: CompanyKpis }.

CompanyKpis shape: { ticker, companyName, cik, lastUpdated, kpis: KpiSeries[] }.

KpiSeries shape: { id, name, category, unit, displayFormat, chartType, values: KpiDataPoint[], sourceRef, discontinued, discontinuedNote }. id is a stable per-ticker identifier (e.g. iphone_revenue). category is one of product_revenue, segment_revenue, unit_economics, etc. chartType is bar or line.

KpiDataPoint shape: { period, date, value, isEstimate }. period is the fiscal label (e.g. Q2 FY2026); date is the ISO close date.

GET /api/v1/stocks/with-kpis

List every ticker with curated KPI coverage. Sorted alphabetically. Builder discovery: render a supported-tickers page or seed a watchlist without 404-probing one ticker at a time. Discovery (no quota cost) -- API key required for identity/abuse tracking, but the call does not consume your monthly quota. Rate-limit-per-minute still applies.

Response: { count, tickers: KpiCoverageEntry[] } where each entry is { ticker, companyName, lastUpdated, kpiCount }.

client = SentiSenseClient(api_key=os.environ["SENTISENSE_API_KEY"])
coverage = client.list_kpi_coverage()
print(f"{coverage.count} tickers covered")
for entry in coverage.tickers[:5]:
    print(f"  {entry.ticker}: {entry.kpiCount} KPIs (refreshed {entry.lastUpdated})")

GET /api/v1/stocks/{ticker}/kpis/types

Lightweight KPI metadata tuples for a ticker, without the full series payload. Mirrors /api/v1/insights/stock/{ticker}/types. Useful for letting an agent or UI decide what to fetch before committing to the heavy data call. Discovery (no quota cost) -- API key required, no quota burn.

Response: bare array of { id, name, category, chartType }. Returns 404 if the ticker has no curated KPIs.

types = client.get_kpi_types("AAPL")
for t in types:
    print(f"  {t.id} ({t.chartType}): {t.name}")

---

Entities API (/api/v1/kb)

GET /api/v1/kb/entities/search

Search the SentiSense ontology for the people, companies, products, and organizations SentiSense tracks, and get the handle to query their metrics. Public (API key required).

Response: array of {name, urlSlug, type, ticker} matches, best first. ticker is null for entities without one. Feed the urlSlug (or ticker) into the Metrics API {entityId} parameter:

GET /api/v1/kb/entities/search?q=pelosi -> [{"name": "Nancy Pelosi", "urlSlug": "Nancy-Pelosi", "type": "person", "ticker": null}]
GET /api/v2/metrics/entity/Nancy-Pelosi/metric/sentiment

People, products, and organizations have the same metrics surface as stocks, so this unlocks queries like a politician's mention volume, a CEO's SentiSense Score (.../entity/Jensen-Huang/metric/sentisense), or crowd sentiment on a product versus its parent ticker.

GET /api/v1/kb/entities/popular

Curated list of high-profile tracked entities (major CEOs, political figures, the Federal Reserve). Public (API key required). Returns {displayName, type, urlSlug, relatedStock} entries; use as an autocomplete seed list without issuing a search.

Metrics API (/api/v2/metrics)

Time series metrics for stocks and entities: mentions, sentiment, social dominance, and more. The {entityId} path segment accepts a stock ticker (e.g. AAPL) or an entity urlSlug (e.g. Nancy-Pelosi); both are case-insensitive, and a ticker-shaped identifier always means the listed company. Discover handles with GET /api/v1/kb/entities/search?q= or GET /api/v1/stocks/{ticker}/entities. An unknown identifier returns 404 entity_not_found with up to three suggestions.

Which handle to store: the urlSlug is the quick, memorable one and is what discovery hands you. For a long-lived reference, such as a tracker that must keep working if an entity is renamed, store the entity id in URL-safe dashed form instead (replace / with -, e.g. kb-person-65). Both forms resolve on every endpoint that takes an {entityId}.

Every metric type (mentions, sentiment, sentisense, social_dominance) is available on the Free tier: no PRO subscription needed. All metrics endpoints are Quota-gated: an API key is required and each request counts against your monthly quota (Free: 1,000 requests/month; PRO: no monthly cap). Per-minute rate limits apply on every tier.

GET /api/v2/metrics/entity/{entityId}/metric/{metricType}

Time series metric data for a stock or entity. Quota-gated -- all metric types (mentions, sentiment, sentisense, social_dominance) are available on the Free tier.

Response: an array of points ordered ascending by timestamp. Each point exposes a flat value scalar alongside the full metricValue object:

[
  {
    "timestamp": 1780372800000,
    "metricType": "SENTIMENT",
    "value": 0.42,
    "metricValue": { "type": "ValueMetricValue", "valueType": "MEAN", "value": { "value": 0.42 } }
  }
]

Read the scalar from the flat value (the polarity for sentiment, the count for mentions). It saves you walking the nested metricValue.value (count metrics) or metricValue.value.value (value metrics), whose depth varies by metric type. A point with no reading omits value. To derive the current reading and its change: points are time-ascending, so the current value is the last point's value, and the change is the last point's value minus the prior point's (or minus the first point's for the whole window). A window with 0 or 1 point has no derivable trend, so widen startTime rather than reporting a change.

GET /api/v2/metrics/entity/{entityId}/distribution/{metricType}

Distribution of a metric across a dimension (e.g., mentions by source). Quota-gated, available on the Free tier.

GET /api/v2/metrics/entity/{entityId}/metric/{metricType}/mean-by/{dimension}

Mean of a metric per dimension value over a time window (e.g., per-source mean sentiment). Quota-gated, available on the Free tier.

Response: flat map of dimension value to mean, e.g. { "NEWS": 0.42, "REDDIT": -0.05 }. For sentiment by source, each value is the average of that source's daily mean readings inside the window; a window with no data returns {}. Returns 400 for an unknown metric type or when startTime is after endTime.

GET /api/v2/metrics/entity/{entityId}/metric/{metricType}/slices

Available slice dimensions for a metric. Quota-gated, available on the Free tier.

GET /api/v2/metrics/entity/{entityId}/baselines/{metricType}

Historical and peer baselines for a metric. Quota-gated, available on the Free tier.

---

Market Mood API (/api/v2/market-mood)

SentiSense's proprietary composite market sentiment index. Combines social sentiment, market direction, risk appetite, social momentum, and S&P 500 trend signals into a single 0-100 score with sector breakdown. Free (API key required). Free for all tiers, but anonymous calls return 401 api_key_required.

GET /api/v2/market-mood

Composite market sentiment score with history and sector breakdown.

Response shape:

{
  "market": {
    "currentScore": 62.88,
    "phase": "Optimism",
    "weeklyChange": -2.3,
    "signals": [
      {"key": "social_sentiment", "label": "Social Sentiment", "value": 54.95, "change": -1.2},
      {"key": "market_direction", "label": "Market Direction", "value": 71.0, "change": 3.1},
      {"key": "fear_gauge", "label": "Risk Appetite", "value": 58.4, "change": null},
      {"key": "social_momentum", "label": "Social Momentum", "value": 62.1, "change": -0.5},
      {"key": "spy_trend", "label": "S&P 500 Trend", "value": 68.9, "change": 2.0}
    ],
    "history": [
      {"date": "2026-04-01", "timestamp": 1743465600000, "score": 65.2,
       "socialSentiment": 56.1, "marketDirection": 72.0, "fearGauge": 61.0,
       "socialMomentum": 63.5, "spyTrend": 70.0}
    ]
  },
  "sectors": {
    "Technology": {"currentScore": 71.2, "phase": "Greed", "weeklyChange": 1.5},
    "Healthcare": {"currentScore": 48.3, "phase": "Neutral", "weeklyChange": -3.1}
  }
}

Phase interpretation (market.phase and each sector's phase, by score): 0-15 Extreme Fear, 16-30 Fear, 31-45 Anxiety, 46-55 Neutral, 56-70 Optimism, 71-85 Greed, 86-100 Extreme Greed. phase is "---" when the score is null.

Node SDK:

const mood = await client.marketMood.get();
console.log(mood.market.currentScore, mood.market.phase);

---

Documents & News API (/api/v1/documents)

Note: Document responses include a url field but no headline or title text. The API provides derived analytics (sentiment, entities, reliability), not source content. The sourceName field identifies the publisher. If your application needs to display titles, the url field links to the original source. Any content retrieval from source URLs is your application's independent action, subject to the source platform's terms. See our API Terms of Service.

GET /api/v1/documents/ticker/{ticker}

News and social posts for a stock with sentiment scores. Public.

Response: { documents: [...], totalCount, searchTicker, source, startDate, endDate }. Each document includes: id, url, source, sourceName, published, averageSentiment, reliability, sentiment[]. Per-entity sentiment classifies each mentioned entity as POSITIVE/NEGATIVE/NEUTRAL.

GET /api/v1/documents/ticker/{ticker}/range

Documents within a date range. Public.

GET /api/v1/documents/entity/{entityId}

Documents mentioning an ontology entity. Public. Use URL-safe format: kb-person-67 instead of kb/person/67.

GET /api/v1/documents/search

Smart search with natural language queries. Public.

GET /api/v1/documents/source/{source}

Latest documents from a specific source. Public.

GET /api/v1/documents/stories

AI-curated news story clusters. Public.

Response: Story objects with a top-level id AND clusterId (both equal to the cluster id -- pass either to /documents/stories/{clusterId}), plus cluster.title, cluster.averageSentiment, tickers, displayTickers, impactScore (0-10), brokeAt (epoch seconds, nullable), cluster.clusteredAt (epoch seconds). Use tickers (bare symbols, e.g. ["AAPL"]) programmatically; displayTickers are human-formatted labels (e.g. ["Apple Inc (AAPL)"]) for display only, do not parse symbols out of them. The cluster.createdAt field (epoch millis) is deprecated and will be removed on or after 2026-08-16; use cluster.clusteredAt.

GET /api/v1/documents/stories/ticker/{ticker}

News stories for a specific stock. Public. Takes limit only (default 5, capped at 20): there is no lookback window here, so days / hours / filterHours are ignored. Use /documents/stories with filterHours for a freshness window.

GET /api/v1/documents/stories/{clusterId}

Full detail for a single story cluster. Public -- Free: 10 story views/