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, YouTube

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.

Building an AI agent? See How to feed real-time market news to your AI agent for the subscribe-don't-scrape pattern, and how to use the url field to fetch full articles on your side.

---

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, YOUTUBE
days	integer	No	7	Lookback period in days (1-365)
hours	integer	No	-	Lookback in hours, 1-8760 (overrides days if set). Out-of-range values return 400
limit	integer	No	200	Max results (capped at 200)

Example Request:

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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, YOUTUBE
sourceName	string | null	Publisher / source name (e.g. "Reuters", "r/wallstreetbets"). Identifies the source; no headline or article text is included.
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	Internal KB entity ID (e.g., kb/company/1). It contains a slash, so it cannot be used in a URL path directly: convert to the URL-safe form (kb-company-1) for GET /entity/{entityId}, or resolve the entity by name via GET /api/v1/kb/entities/search?q= and use its urlSlug
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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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 SentiSense ontology 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 (1-365)
hours	integer	No	-	Lookback in hours, 1-8760 (overrides days). Out-of-range values return 400
limit	integer	No	50	Max results (capped at 200)

Example Request:

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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, YOUTUBE
days	integer	No	7	Lookback in days (1-365)
hours	integer	No	-	Lookback in hours, 1-8760 (overrides days). Out-of-range values return 400
limit	integer	No	100	Max results (capped at 500)
sort	string	No	latest	Result ordering. latest: newest first. top: reliability-first, grouping recent documents into short freshness buckets and ranking by publisher reliability within each bucket, so recent content from high-authority publishers surfaces above low-authority floods. An unrecognized value returns 400.

Example Request:

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/documents/source/REDDIT?days=1&limit=50"

Example Request (reliability-first ordering):

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/documents/source/NEWS?sort=top&hours=6&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: 10 story detail views/mo, PRO: unlimited). The detail response includes the full narrative, bull/bear perspectives, and citation links.

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 -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "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.clusteredAt	long	When the cluster was assembled by our pipeline (epoch seconds).
cluster.createdAt	long	Deprecated 2026-05-16, removed on or after 2026-08-16. Epoch millis. Use cluster.clusteredAt.
tickers	array	Bare ticker symbols for programmatic use (e.g., ["AAPL"]). Use these to filter or look up stocks.
displayTickers	array	Human-formatted labels for display only (e.g., ["Apple Inc (AAPL)"]). Do not parse symbols out of these; use tickers.
primaryEntityNames	array	Primary entity names
impactScore	double	Impact score (0.0-10.0)
brokeAt	long | null	When the story broke (epoch seconds). Null when no representative document timestamp is available.

---

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)

No lookback window on this endpoint. It always returns the most recent stories for the ticker, so days, hours, and filterHours are ignored if you pass them. Use GET /stories with filterHours when you need a freshness window, or the /documents/ticker/{ticker} endpoints with days / hours for article-level lookback.

Example Request:

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

---

GET /stories/{clusterId}

Returns the full detail for a single AI-curated story: the AI-written narrative, bull/bear perspectives, computed metrics, and citation links back to the original articles. Get the clusterId from the id field of the /stories or /stories/ticker/{ticker} list responses.

Access: Quota-gated. Free tier: 10 story detail views per month (each full-detail response consumes one view). PRO: unlimited. When the monthly allowance is exhausted, the endpoint stops returning full detail until the next monthly cycle.

Parameters:

Parameter	Type	Required	Default	Description
clusterId	path	Yes	-	Story cluster ID (from the /stories list endpoints)

Example Request:

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/documents/stories/CLUSTER_ID"

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

Field	Type	Description
id	string	Story cluster ID
createdAt	long	When the cluster was created
lastUpdatedAt	long | null	Last content update
title	string	AI-generated story title
summarizedContent	string	AI-written summary
narrativeBody	string	Full AI-written narrative (markdown with [docN] citation references)
bullishView	string	AI-written bull perspective
bearishView	string	AI-written bear perspective
aspectPerspectives	array	Per-aspect perspective entries
citationLinks	object	Map of docN references in narrativeBody to public article URLs
averageSentiment	double	Aggregate sentiment (-1.0 to 1.0)
momentumScore	double | null	Story momentum score
aiConfidence	double | null	Model confidence in the story content
clusterSize	int	Number of source articles
sourcesList	array	Source types contributing to the story
primaryCategory	string	Primary story category
dominantEventType	string	Dominant event type
publishersList / primaryPublisher / topPublishers	array / string / array	Publisher name metadata (names only, no content)
tickers	array	Bare ticker symbols for programmatic use
displayTickers	array	Human-formatted labels for display only
primaryEntityNames	array	Primary entity names
relatedEntities	array	Related entities: {entityId, name, ticker, type, isPrimary, frequency}
archived	boolean	Whether the story is archived
totalDocuments	int	Total documents in the cluster

No headlines policy: consistent with the rest of the Documents API, publisher headlines, article text, and images are never included. The title, narrativeBody, and perspectives are AI-generated by SentiSense, and citationLinks point to the original sources.