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

| 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) | | Discovery (no quota cost) | API key required (identity/abuse tracking), but the call does not burn your monthly quota. Rate-limit-per-minute still applies. Used for lightweight metadata endpoints like /stocks/with-kpis and /stocks/{ticker}/kpis/types. | | PRO only | Requires PRO subscription |

Rate Limits

| Tier | Requests/Month | Rate | |------|----------------|------| | Free | 1,000 | 30 requests/minute | | PRO ($15/mo) | Unlimited | 300 requests/minute |

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.

| You pass | Resolves to | Reason | |----------|-------------|--------| | GOOG | GOOGL | Alphabet Class C resolves to Class A | | BRK.A, BRK-A, BRKA | BRK.B | Berkshire Class A resolves to Class B | | BRK-B, BRKB | BRK.B | Punctuation variants normalized |

Aliasing applies to research endpoints (analyst, KPIs, insights, insider, institutional holders, politicians filings). 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?reportDate={date} for quarterly institutional positioning
• 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 financial statement data
• 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

---

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 any institutional endpoint to get valid reportDate values
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. 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: for the earnings calendar use /api/v1/calendar/earnings; for reported financials use /api/v1/stocks/fundamentals
• /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: $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).

| 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 | 1D, 5D, 1W, 1M, 3M, 6M, 1Y, ALL (default: 1M) | | range | string | No | Alias: 5d, 1mo, 3mo, 6mo, 1y (alternative to timeframe) |

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 and weekly 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 }. The timestamp is a numeric epoch milliseconds value (not a string).

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/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.

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, 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. Cached 15 s server-side.

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}")

---

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).

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 ti

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SentiSenseApp
• Source: SentiSenseApp/skills
• License: MIT

Install and usage instructions live in the source repository linked above.