Documents & News API

Overview

The Documents & News API provides access to SentiSense's real-time sentiment metrics pipeline. Every document is enriched with AI-powered sentiment analysis, entity extraction, and reliability scoring.

Data sources: News (600+ publishers), Reddit, X (Twitter), Substack

Key features:

• Per-entity sentiment classification (e.g., an article about Apple and Google may be POSITIVE for Apple but NEGATIVE for Google)
• Smart search with natural language query parsing
• News clustering into "stories" that group related articles together
• Publisher reliability scoring

Note: Document responses include sentiment metrics, reliability scores, source URLs, and timestamps. Use the url field to link through to the original article.

---

GET /ticker/{ticker}

Returns the latest news articles and social media posts mentioning a specific stock ticker.

Access: Public

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol (e.g., AAPL)
source	string	No	all	Filter by source: NEWS, REDDIT, X, SUBSTACK
days	integer	No	7	Lookback period in days (1-365)
hours	integer	No	-	Lookback in hours (overrides days if set)
limit	integer	No	200	Max results (capped at 200)

Example Request:

curl "https://app.sentisense.ai/api/v1/documents/ticker/AAPL?source=NEWS&days=3&limit=10"

from sentisense import SentiSenseClient
client = SentiSenseClient()
docs = client.get_documents_by_ticker("AAPL", source="NEWS", days=3, limit=10)

Response Schema:

Field	Type	Description
documents	array	List of document objects (see Document schema below)
totalCount	int	Total matching documents
searchTicker	string	Ticker used for search
source	string	Source filter applied
startDate	string	Query start date (ISO)
endDate	string	Query end date (ISO)

Document object:

Field	Type	Description
id	string	Unique document ID
url	string	Direct link to source article
source	string	NEWS, REDDIT, X, SUBSTACK
published	long	Epoch timestamp (seconds)
averageSentiment	double	Overall sentiment score (-1.0 to 1.0)
reliability	double	Publisher reliability score
sentiment	array	Per-entity sentiment entries (see Sentiment Entry below)

Sentiment Entry object:

Field	Type	Description
ticker	string|null	Stock ticker symbol (null for non-company entities)
name	string|null	Human-readable entity name (e.g., "Apple Inc.", "Elon Musk")
entityId	string	KB entity ID (e.g., kb/company/1) — use with GET /entity/{entityId}
entityType	string	Entity type: COMPANY, PERSON, etc.
sentiment	string	POSITIVE, NEGATIVE, or NEUTRAL

---

GET /ticker/{ticker}/range

Returns documents for a stock ticker within a specific date range. Useful for historical research.

Access: Public

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol
startDate	date (ISO)	Yes	-	Start date (e.g., 2025-01-01)
endDate	date (ISO)	Yes	-	End date (e.g., 2025-01-31)
source	string	No	all	Filter by source
limit	integer	No	100	Max results (capped at 200)

Example Request:

curl "https://app.sentisense.ai/api/v1/documents/ticker/TSLA/range?startDate=2025-01-01&endDate=2025-01-31&limit=50"

---

GET /entity/{entityId}

Returns documents mentioning a knowledge base entity (person, product, organization). Entity IDs use URL-safe format with dashes instead of slashes.

Access: Public

Parameters:

Parameter	Type	Required	Default	Description
entityId	path	Yes	-	KB entity ID in URL-safe format (e.g., kb-person-67)
source	string	No	all	Filter by source
days	integer	No	7	Lookback in days
hours	integer	No	-	Lookback in hours (overrides days)
limit	integer	No	50	Max results (capped at 200)

Example Request:

curl "https://app.sentisense.ai/api/v1/documents/entity/kb-person-67?days=14"

---

GET /search

Smart search with natural language query parsing. The query is analyzed to extract stock tickers, entity names, and free-text keywords, then used to find matching documents.

Access: Public

Parameters:

Parameter	Type	Required	Default	Description
query	string	Yes	-	Natural language query (e.g., "AAPL TSLA earnings")
source	string	No	all	Filter by source
days	integer	No	7	Lookback in days
limit	integer	No	200	Max results (capped at 500)

Query examples:

• "AAPL" — Documents about Apple
• "AAPL, NVDA" — Documents about Apple or NVIDIA
• "Elon Musk, TSLA" — Documents about Elon Musk or Tesla
• "earnings report" — Documents containing "earnings report"
• "AAPL earnings beat" — Apple + text search for "earnings beat"

Example Request:

curl "https://app.sentisense.ai/api/v1/documents/search?query=NVDA+earnings&days=3&limit=20"

---

GET /source/{source}

Returns the latest documents from a specific source type, across all stocks.

Access: Public

Parameters:

Parameter	Type	Required	Default	Description
source	path	Yes	-	Source type: NEWS, REDDIT, X, SUBSTACK
days	integer	No	7	Lookback in days
hours	integer	No	-	Lookback in hours
limit	integer	No	100	Max results (capped at 500)

Example Request:

curl "https://app.sentisense.ai/api/v1/documents/source/REDDIT?days=1&limit=50"

---

GET /stories

Returns the latest AI-curated news stories. Stories are clusters of related articles grouped by topic, with AI-generated titles and sentiment analysis.

Access: Public (list returns slim data — title, sentiment, impact, tickers)

Story detail is available at GET /stories/{clusterId} and is Quota-gated (Free: 25 views/mo, PRO: unlimited). The detail response includes the full narrative, bull/bear perspectives, and source articles.

Parameters:

Parameter	Type	Required	Default	Description
limit	integer	No	20	Max stories (capped at 50)
days	integer	No	7	Lookback in days (max 15)
offset	integer	No	0	Pagination offset
filterHours	integer	No	-	Filter to stories from last N hours

Example Request:

curl "https://app.sentisense.ai/api/v1/documents/stories?limit=10"

Response Schema (Story object):

Field	Type	Description
cluster.id	string	Story ID
cluster.title	string	AI-generated story title
cluster.clusterSize	int	Number of source articles
cluster.averageSentiment	double	Aggregate sentiment (-1.0 to 1.0)
cluster.createdAt	long	Epoch millis
displayTickers	array	Ticker badges (e.g., ["Apple Inc (AAPL)"])
tickers	array	Raw tickers (e.g., ["AAPL"])
primaryEntityNames	array	Primary entity names
impactScore	double	Impact score (0.0-10.0)
brokeAt	long	When the story broke (epoch seconds)

---

GET /stories/ticker/{ticker}

Returns news stories (clusters) for a specific stock ticker.

Access: Public

Parameters:

Parameter	Type	Required	Default	Description
ticker	path	Yes	-	Stock ticker symbol
limit	integer	No	5	Max stories (capped at 20)

Example Request:

curl "https://app.sentisense.ai/api/v1/documents/stories/ticker/AAPL?limit=10"