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. Generate keys at Settings > Developer Console.
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.
Authentication
# Include API key in header
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
"https://app.sentisense.ai/api/v1/..."
from sentisense import SentiSenseClient
client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
All API endpoints require an API key. Generate one for free at Settings > Developer Console.
Access Tiers
| Badge | Meaning |
|---|
| Public | Available on all tiers (Free and PRO) |
| Public (preview) | Free gets limited preview; PRO gets full data |
| Quota-gated | Consumes monthly quota (Free: limited, PRO: unlimited) |
| PRO only | Requires PRO subscription |
Rate Limits
| Tier | Requests/Month | Rate |
|---|
| Free | 1,000 | 15 requests/minute |
| PRO ($15/mo) | 100,000 | 120 requests/minute |
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 /insider/activity for market-wide insider buying/selling
GET /institutional/flows?reportDate={date} for quarterly institutional positioning
GET /politicians/activity for congressional STOCK Act trades
GET /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 /v2/metrics/entity/{ticker}/metric/sentiment for sentiment time series
GET /v2/metrics/entity/{ticker}/baselines/sentiment for anomaly detection (3-sigma deviations)
GET /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 /politicians/activity for recent congressional trades across all members
GET /politicians/member/{slug} for individual politician profiles and trade history
GET /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 /stocks/{ticker}/ai-summary?depth=deep for the full AI analysis report
GET /insights/stock/{ticker} for actionable trading signals
GET /stocks/fundamentals?ticker={ticker} for financial statement data
GET /documents/ticker/{ticker} for recent news context
Market Dashboard
Real-time market overview combining prices, sentiment, and top signals.
GET /stocks/market-status to check if the market is open
GET /market-summary for AI-generated market headline and analysis
GET /insights/market for the top market-moving signals right now
GET /stocks/prices?tickers=SPY,QQQ,IWM,DIA for index tracking
Agent Tips
Workflow Pattern
- Call
GET /stocks/market-status first to check if the market is open
- Call
GET /institutional/quarters before any institutional endpoint to get valid reportDate values
- All PRO-gated endpoints return
{isPreview, previewReason, data}. Always access response["data"] (or response.data)
- Use
lookbackDays (1-365) on insider and politician endpoints to control the time window
Common Mistakes
- Do NOT hardcode
reportDate for institutional endpoints. Always fetch from /quarters first; quarters change as new SEC filings come in
- 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: we do not have options flow or dark pool data
/api/v1/earnings: use /api/v1/stocks/fundamentals for financial data
/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.
| Param | Type | Required | Description |
|---|
ticker | string | Yes | Stock ticker (e.g., AAPL) |
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
"https://app.sentisense.ai/api/v1/stocks/price?ticker=AAPL"
Response: { ticker, currentPrice, change, changePercent, previousClose, volume, timestamp }
GET /api/v1/stocks/prices
Batch real-time prices. Public.
| Param | Type | Required | Description |
|---|
tickers | string | Yes | Comma-separated (e.g., AAPL,TSLA,NVDA) |
GET /api/v1/stocks/chart
Historical OHLCV chart data. Public.
| Param | Type | Required | Description |
|---|
ticker | string | Yes | Stock ticker |
timeframe | string | No | 1M, 3M, 6M, 1Y (default: 1M) |
range | string | No | Alias: 5d, 1mo, 3mo, 6mo, 1y (alternative to timeframe) |
GET /api/v1/stocks
List all tracked ticker symbols. Public.
GET /api/v1/stocks/detailed
All stocks with company name, KB entity ID, and URL slug. Public.
GET /api/v1/stocks/popular
Popular stock tickers. Public.
GET /api/v1/stocks/images
Company logo URLs. Public.
| Param | Type | Required | Description |
|---|
tickers | string | Yes | Comma-separated tickers (max 600) |
GET /api/v1/stocks/descriptions
Company profiles with branding, sector, market cap. Public.
| Param | Type | Required | Description |
|---|
tickers | string | Yes | Comma-separated tickers |
GET /api/v1/stocks/{ticker}/profile
Company profile (CEO, sector, industry). Public.
GET /api/v1/stocks/{ticker}/similar
Peer/similar stocks. Public.
| Param | Type | Required | Default | Description |
|---|
limit | int | No | 5 | Max results |
GET /api/v1/stocks/{ticker}/entities
Related knowledge base entities (CEO, products, partners). Public.
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.
| Param | Type | Required | Default | Description |
|---|
depth | string | No | basic | basic or deep |
forceRefresh | boolean | No | false | Generate fresh report |
GET /api/v1/stocks/{ticker}/metrics/{metricType}/breakdown
Sentiment or mention metrics breakdown by sub-entities. Public.
| Param | Type | Required | Description |
|---|
metricType | path | Yes | sentiment or mentions |
startTime | long | Yes | Start time in epoch ms |
endTime | long | Yes | End time in epoch ms |
GET /api/v1/stocks/market-status
Current market open/closed status. API key required.
GET /api/v1/stocks/fundamentals
Financial statement data. Public.
| Param | Type | Required | Default | Description |
|---|
ticker | string | Yes | - | Stock ticker |
timeframe | string | No | quarterly | quarterly or annual |
fiscalPeriod | string | No | - | e.g., Q4 |
fiscalYear | int | No | - | e.g., 2024 |
GET /api/v1/stocks/fundamentals/current
Most recent fundamental data snapshot. Public.
GET /api/v1/stocks/fundamentals/periods
Available fiscal periods. Public.
GET /api/v1/stocks/fundamentals/historical/ratios
Historical P/E and financial ratios. Public. Note: data availability depends on upstream provider; may return 404 for some tickers.
GET /api/v1/stocks/fundamentals/historical/revenue
Historical revenue data. 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.
Metrics API (/api/v2/metrics)
Time series metrics for stocks and entities: mentions, sentiment, social dominance, and more. Computed from serving data with proper entity resolution (tickers are resolved to KB entities automatically).
GET /api/v2/metrics/entity/{entityId}/metric/{metricType}
Time series metric data for a stock or entity. All metric types (mentions, sentiment, sentisense, social_dominance) are Public (free for all users).
| Param | Type | Required | Default | Description |
|---|
entityId | path | Yes | - | Stock ticker (e.g., AAPL) or KB entity ID |
metricType | path | Yes | - | mentions, sentiment, sentisense, social_dominance |
startTime | long | No | 7 days ago | Epoch milliseconds |
endTime | long | No | now | Epoch milliseconds |
maxDataPoints | int | No | - | Downsample to N data points |
GET /api/v2/metrics/entity/{entityId}/distribution/{metricType}
Distribution of a metric across a dimension (e.g., mentions by source). Public (same quota rules as above).
| Param | Type | Required | Default | Description |
|---|
entityId | path | Yes | - | Stock ticker or KB entity ID |
metricType | path | Yes | - | Metric type key |
dimension | string | Yes | - | Dimension to slice by (e.g., source) |
startTime | long | No | 7 days ago | Epoch milliseconds |
endTime | long | No | now | Epoch milliseconds |
GET /api/v2/metrics/entity/{entityId}/metric/{metricType}/slices
Available slice dimensions for a metric. Public.
GET /api/v2/metrics/entity/{entityId}/baselines/{metricType}
Historical and peer baselines for a metric. Public.
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.
| Param | Type | Required | Default | Description |
|---|
source | string | No | all | NEWS, REDDIT, X, SUBSTACK |
days | int | No | 7 | Lookback in days (1-365) |
hours | int | No | - | Lookback in hours (overrides days) |
limit | int | No | 200 | Max results (capped at 200) |
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.
| Param | Type | Required | Description |
|---|
startDate | ISO date | Yes | e.g., 2025-01-01 |
endDate | ISO date | Yes | e.g., 2025-01-31 |
source | string | No | Filter by source |
limit | int | No | Max results (capped at 200) |
GET /api/v1/documents/entity/{entityId}
Documents mentioning a knowledge base 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.
| Param | Type | Required | Default | Description |
|---|
query | string | Yes | - | e.g., AAPL earnings, Elon Musk TSLA |
source | string | No | all | Filter by source |
days | int | No | 7 | Lookback in days |
limit | int | No | 200 | Max results (capped at 500) |
GET /api/v1/documents/source/{source}
Latest documents from a specific source. Public.
| Param | Type | Required | Description |
|---|
source | path | Yes | NEWS, REDDIT, X, SUBSTACK |
days | int | No | Lookback in days |
limit | int | No | Max results (capped at 500) |
GET /api/v1/documents/stories
AI-curated news story clusters. Public.
| Param | Type | Required | Default | Description |
|---|
limit | int | No | 20 | Max stories (capped at 50) |
days | int | No | 7 | Lookback in days (max 15) |
offset | int | No | 0 | Pagination offset |
Response: Story objects with cluster.title, cluster.averageSentiment, displayTickers, impactScore (0-10), brokeAt.
GET /api/v1/documents/stories/ticker/{ticker}
News stories for a specific stock. Public.
Institutional Flows API (/api/v1/institutional)
Data from SEC 13F-HR filings. Filer categories: INDEX_FUND, HEDGE_FUND, ACTIVIST, PENSION, BANK, INSURANCE, MUTUAL_FUND, SOVEREIGN_WEALTH, ENDOWMENT, OTHER.
Important: All institutional endpoints (except /quarters) require a reportDate parameter. Always call GET /quarters first to get valid dates; do not hardcode them. Use the reportDate from the first (most recent) quarter in subsequent calls.
GET /api/v1/institutional/quarters
Available 13F reporting quarters. Public. Call this first.
Response: array of { value, label, reportDate } objects sorted newest-first. Use the reportDate field (e.g., "2025-12-31") when calling other institutional endpoints.
GET /api/v1/institutional/flows
Aggregate institutional buying/selling per ticker. Public (preview) -- Free: top 5, PRO: full data.
| Param | Type | Required | Description |
|---|
reportDate | ISO date | Yes | The reportDate from /quarters (e.g., 2025-12-31) |
limit | int | No | Max results per direction (default: 50, max: 100) |
Response: { isPreview, previewReason, data: { inflows: [...], outflows: [...] } }. Each flow includes net share changes, new/closed positions, and per-category breakdowns (indexFundNetChange, hedgeFundNetChange, etc.).
GET /api/v1/institutional/holders/{ticker}
Institutional holders for a stock. Public (preview) -- Free: top 5, PRO: full data.
| Param | Type | Required | Description |
|---|
reportDate | ISO date | Yes | Quarter end date |
Response includes filer name, category, shares, value, change type (NEW/INCREASED/DECREASED/SOLD_OUT/UNCHANGED).
GET /api/v1/institutional/activist
Activist investor positions (NEW or INCREASED stakes). Public (preview) -- Free: top 3, PRO: full data.
| Param | Type | Required | Description |
|---|
reportDate | ISO date | Yes | Quarter end date |
GET /api/v1/institutional/bonds
Convertible bond flows grouped by base ticker. Public (preview) -- Free: top 3, PRO: full data.
| Param | Type | Required | Description |
|---|
reportDate | ISO date | Yes | Quarter end date |
GET /api/v1/institutional/options
Institutional options activity with call/put breakdown. Public (preview) -- Free: top 3, PRO: full data.
| Param | Type | Required | Description |
|---|
reportDate | ISO date | Yes | Quarter end date |
Insider Trading API (/api/v1/insider)
SEC Form 4 insider trading data: track buys, sells, awards, and exercises by company officers, directors, and 10%+ shareholders. Updated daily. Includes cluster buy detection (a historically bullish signal).
Insider relationships: OFFICER, DIRECTOR, TEN_PCT_OWNER, OTHER. Each filer also has independent officer, director, tenPctOwner booleans (a person can be both officer and director).
Transaction types: BUY, SELL, EXERCISE, AWARD, GIFT, OTHER.
GET /api/v1/insider/activity
Market-wide insider buying and selling aggregated by ticker. Public (preview) -- Free: top 5, PRO: full data.
| Param | Type | Required | Default | Description |
|---|
lookbackDays | int | No | 90 | Days to look back (1-365) |
Response (Free/unauthenticated): { isPreview: true, previewReason: "LOGIN_REQUIRED" | "PRO_REQUIRED", data: { buys: [...], sells: [...] } }. PRO: { isPreview: false, data: { buys: [...], sells: [...] } }. Each entry: ticker, companyName, tradeCount, insiderCount, totalShares, totalValue, latestDate, latestInsider, latestTitle.
GET /api/v1/insider/trades/{ticker}
Insider transactions for a specific stock, newest first. Public (preview) -- Free: top 5, PRO: full data.
| Param | Type | Required | Default | Description |
|---|
ticker | path | Yes | - | Stock ticker (e.g., AAPL) |
lookbackDays | int | No | 90 | Days to look back (1-365) |
Response: { isPreview: bool, previewReason: string|null, data: [...] }. Free: top 5 trades, PRO: full list. Each trade: insiderName, insiderTitle, insiderRelation, officer, director, tenPctOwner, transactionDate, filedDate, transactionCode, transactionType, securityTitle, sharesTransacted, pricePerShare, totalValue, sharesOwnedAfter, directOwnership, rule10b51.
client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
trades = client.get_insider_trades("AAPL", lookback_days=90)
for t in trades["data"]:
print(f"{t['transactionDate']} {t['insiderName']} {t['transactionType']} {t['sharesTransacted']} shares")
GET /api/v1/insider/cluster-buys
Cluster buy signals: stocks where 3+ distinct insiders purchased recently. Public (preview) -- Free: top 3, PRO: full data.
| Param | Type | Required | Default | Description |
|---|
lookbackDays | int | No | 90 | Days to look back (1-365) |
Response: { isPreview: bool, previewReason: string|null, data: [...] }. Free: top 3 signals, PRO: full list. Each entry: { ticker, companyName, insiderCount, tradeCount, totalShares, totalValue, firstBuyDate, lastBuyDate }.
Politicians Trading API (/api/v1/politicians)
Congressional STOCK Act trading disclosures: purchases, sales, and exercises by U.S. Senators and Representatives. Updated daily from official filings.
Chambers: SENATE, HOUSE.
Transaction types: PURCHASE, SALE, EXCHANGE, OTHER.
Amount ranges: STOCK Act disclosures report dollar amounts as ranges (e.g., "$1,001 - $15,000"), not exact values. The API returns the raw range string plus parsed amountMin/amountMax.
GET /api/v1/politicians/activity
Recent congressional trades across all politicians. Public (preview) -- Free: top 5, PRO: full data.
| Param | Type | Required | Default | Description |
|---|
lookbackDays | int | No | 90 | Days to look back (1-365) |
Response: { isPreview, previewReason, data: [...] }. Each trade: politicianName, firstName, lastName, chamber, party, state, bioguideId, imageUrl, ticker, assetDescription, assetType, transactionType, transactionDate, disclosureDate, disclosureDelayDays, amountRange, amountMin, amountMax, owner, urlSlug.
client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
activity = client.get_politician_activity(lookback_days=90)
for trade in activity["data"]:
print(f"{trade['politicianName']} ({trade['party']}-{trade['state']}): {trade['transactionType']} {trade['ticker']}")
GET /api/v1/politicians/filings/{ticker}
Congressional trades for a specific stock, newest first. Public (preview) -- Free: top 3, PRO: full data.
| Param | Type | Required | Default | Description |
|---|
ticker | path | Yes | - | Stock ticker (e.g., NVDA) |
lookbackDays | int | No | 90 | Days to look back (1-365) |
Response: same preview wrapper and trade object schema as /activity.
GET /api/v1/politicians/members
All tracked politicians with trading summaries, sorted by total trade count. Public (preview) -- Free: top 5, PRO: full list.
No parameters.
Response: { isPreview, previewReason, data: [...] }. Each entry: urlSlug, displayName, firstName, lastName, chamber, party, state, bioguideId, imageUrl, totalTrades, purchaseCount, saleCount, latestTradeDate.
GET /api/v1/politicians/member/{slug}
Detailed profile for a single politician: summary stats, recent trades, and top tickers. Public (preview) -- Free: preview-wrapped, PRO: full detail.
| Param | Type | Required | Default | Description |
|---|
slug | path | Yes | - | Politician URL slug (from /members) |
Response: { isPreview, previewReason, data: { profile: {...}, recentTrades: [...], topTickers: [...] } }.
Insights API (/api/v1/insights)
AI-generated trading signals for stocks and the overall market. Each insight identifies a specific pattern: insider cluster buying, institutional position changes, volume anomalies, sentiment baseline deviations, and more. Sorted by urgency then confidence.
Insight fields: insightId, insightType, category (SENTIMENT/TRENDING/TECHNICAL/FUNDAMENTAL/PERSONALIZED), insightText, confidence (0.0-1.0), urgency (low/medium/high), generatedAt (epoch seconds), docRefs ([{url, type}]).
Response shape (all tiers): { isPreview, previewReason, data: [...] }. Free: top N insights, PRO: full list.
GET /api/v1/insights/stock/{ticker}
AI insights for a specific stock, sorted by urgency (high first) then confidence. Public (preview) -- Free: top 3, PRO: full list.
| Param | Type | Required | Default | Description |
|---|
ticker | path | Yes | - | Stock ticker (e.g., AAPL) |
urgency | string | No | - | Filter by urgency: low, medium, or high |
insightType | string | No | - | Filter by type (e.g., insider_buy_signal) |
client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
result = client.get_stock_insights("AAPL", urgency="high")
for i in result["data"]:
print(f"[{i['urgency'].upper()}] {i['insightType']}: {i['insightText'][:80]}")
GET /api/v1/insights/market
Market-level AI insights: insider buying trends, institutional rotation, and top high-urgency stock signals. Public (preview) -- Free: top 5, PRO: full list.
No parameters required.
result = client.get_market_insights()
for i in result["data"]:
print(f"[{i['urgency'].upper()}] {i['insightText'][:100]}")
GET /api/v1/insights/stock/{ticker}/types
Available insight types for a ticker. Public -- no authentication required.
| Param | Type | Required | Description |
|---|
ticker | path | Yes | Stock ticker (e.g., AAPL) |
Response: string array, e.g. ["insider_buy_signal", "institutional_position_change", "volume_anomaly_high"].
Market Summary API (/api/v1/market-summary)
AI-generated market overview with headline analysis and top active stocks.
GET /api/v1/market-summary
AI market summary with headline, markdown analysis, and mention data. Public. No parameters required.
Response:
| Field | Type | Description |
|---|
totalMentions | long | Total mentions across all tracked stocks |
topActiveStocks | string[] | Most active tickers by mention volume |
lastUpdated | long | Epoch milliseconds when data was last updated |
headline | string? | 1-2 sentence market punchline |
expandedContent | string? | Full markdown analysis |
generatedAt | long? | Epoch seconds when AI summary was generated |
Error Codes
| Code | Meaning |
|---|
| 200 | Success |
| 400 | Bad request (missing/invalid parameters) |
| 401 | Unauthorized (invalid or missing API key) |
| 403 | Forbidden (insufficient tier) |
| 404 | Resource not found |
| 429 | Rate limit or quota exceeded |
| 500 | Internal server error |
Getting Started
- Sign up at app.sentisense.ai and generate a free API key in Settings > Developer Console
- Start calling -- all you need is the API key in a header. No SDK install required:
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
"https://app.sentisense.ai/api/v1/stocks/price?ticker=AAPL"
- Upgrade to PRO ($15/mo) for full institutional flows, AI reports, politician data, and 100K requests/month
SDKs (Optional Convenience)
SDKs are thin wrappers around the REST API. As an AI agent, you are encouraged to call endpoints directly with HTTP requests rather than installing packages. If you do want to use an SDK, review the source first:
Python: github.com/SentiSenseApp/sentisense (pip install sentisense)
from sentisense import SentiSenseClient
client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
price = client.get_stock_price("AAPL")
Node.js: github.com/SentiSenseApp/sentisense-node (npm install sentisense)
import SentiSense from 'sentisense';
const client = new SentiSense({ apiKey: 'ss_live_YOUR_KEY' });
const price = await client.stocks.getPrice('AAPL');
Note: This skill file is updated frequently as new features ship. For the latest version, check sentisense.ai/skill.md.
SentiSense is a product of Compass AI Data Services, LLC. This data is for informational purposes only -- not investment advice.