Endpoints

All endpoints below accept Authorization: Bearer es_YOUR_KEY_HERE and are read-only. The base URL is https://api.echosift.io.

Dashboard

GET /api/dashboard/overview

Returns a single payload to hydrate a main dashboard: total signals, new signals last 7 days, average growth rate, top providers, top-5 by score, top-5 trending, and last updated timestamp. Cached 5 minutes.

Response fields:

Field	Type	Description
`totalSignals`	long	Total pain signals in the corpus
`newSignalsLast7d`	long	New signals detected in the last 7 days
`avgGrowthRate`	double	Average growth rate across all signals
`topProviders`	string[]	Top source providers by mention count
`activeSourcesCount`	long	Count of distinct active source providers
`topSignals`	PainSignalListItem[]	Top 5 by composite score
`trending`	PainSignalListItem[]	Top 5 by growth rate
`lastUpdatedAt`	ISO instant	When this overview was last computed

curl https://api.echosift.io/api/dashboard/overview \
  -H "Authorization: Bearer es_YOUR_KEY_HERE"

GET /api/dashboard/trending

Top N signals by growth rate. Cached 5 minutes.

Param	Type	Default	Description
`limit`	int	10	Max results (max 10)

curl "https://api.echosift.io/api/dashboard/trending?limit=5" \
  -H "Authorization: Bearer es_YOUR_KEY_HERE"

Returns an array of PainSignalListItem.

GET /api/dashboard/emerging

Low-volume, high-growth signals.

Param	Type	Default	Description
`maxVolume`	long	100	Max mention volume threshold
`minGrowth`	double	0.5	Minimum growth rate
`limit`	int	10	Max results (max 10)

curl "https://api.echosift.io/api/dashboard/emerging?maxVolume=80&minGrowth=1.0" \
  -H "Authorization: Bearer es_YOUR_KEY_HERE"

GET /api/dashboard/top

Top signals by a configurable metric.

Param	Type	Default	Description
`metric`	string	`score`	Sort by `score`, `growth`, or `volume`
`limit`	int	10	Max results (max 10)

GET /api/dashboard/timeline

Global activity timeline across top signals.

Param	Type	Default	Description
`days`	int	30	Days of history (1-90)

GET /api/dashboard/timeline/by-macro-area

Daily mention buckets grouped by macro area (for multi-series charts).

Param	Type	Default	Description
`days`	int	30	Days of history (1-90)

Returns MacroAreaTimelineBucket[]:

Field	Type	Description
`date`	LocalDate	Bucket date
`macroArea`	string	Area enum value
`mentionCount`	long	Mention count for this date and area

Pain Signals

GET /api/pain-signals

Paginated list with optional filters.

Param	Type	Default	Description
`query`	string	-	Text search on topic and summary
`sortBy`	string	`score`	`score`, `growth`, `volume`, or `lastSeenAt`
`direction`	string	`desc`	`asc` or `desc`
`page`	int	0	Page number (0-based)
`size`	int	20	Page size (max 100)
`minScore`	double	-	Minimum score (inclusive)
`minDocumentDiversity`	int	-	Minimum distinct source repos
`macroArea`	string	-	One of 11 taxonomy values (case-sensitive)
`painType`	string	-	`bug`, `feature_request`, `complaint`, or `question`
`owner`	string	-	Substring match on the top GitHub owner

Returns PageResponse<PainSignalListItem>.

PainSignalListItem fields:

Field	Type	Description
`id`	string	Signal UUID
`topic`	string	LLM-generated topic label
`score`	double	Composite pain score [0-100]
`volume`	long	Total mention count
`growth`	double	Growth rate
`lastSeenAt`	ISO instant	Most recent mention
`macroArea`	string	Taxonomy area (nullable)
`macroAreaConfidence`	double	Classifier confidence [0-1] (nullable)
`mentionsLastWindow`	int	Mentions in the last 7-day window (nullable)
`mentionsPrevWindow`	int	Mentions in the prior 7-day window (nullable)
`painType`	string	Classification (nullable)
`uniqueOwnerCount`	int	Distinct GitHub owners
`topOwnerName`	string	Top GitHub owner (nullable for non-GitHub)
`topOwnerDominancePct`	int	Share of chunks from top owner

curl "https://api.echosift.io/api/pain-signals?macroArea=AI_AGENTS_LLM&sortBy=growth&size=20" \
  -H "Authorization: Bearer es_YOUR_KEY_HERE"

GET /api/pain-signals/{id}

Full detail for a single signal.

Additional fields beyond list item:

Field	Type	Description
`summary`	string	LLM-generated description
`chunkCount`	long	Evidence chunks attached
`firstSeenAt`	ISO instant	First mention timestamp
`createdAt`	ISO instant	Cluster creation timestamp
`updatedAt`	ISO instant	Cluster last update timestamp

curl "https://api.echosift.io/api/pain-signals/SIGNAL_UUID" \
  -H "Authorization: Bearer es_YOUR_KEY_HERE"

GET /api/pain-signals/{id}/stats

Aggregated statistics with 7-day comparison.

Field	Type	Description
`painSignalId`	string	Signal UUID
`totalMentions`	long	All-time mention count
`last7dMentions`	long	Last 7 days
`prev7dMentions`	long	Prior 7 days
`growthRate`	double	(last7d - prev7d) / max(prev7d, 1)
`sourceDistribution`	SourceDistribution[]	Breakdown by provider

GET /api/pain-signals/{id}/timeline

Daily mention buckets.

Param	Type	Default	Description
`days`	int	30	Days of history (1-365)

Returns { painSignalId, buckets: [{date, count}], totalMentions }.

GET /api/pain-signals/{id}/history

Tracked owner count, score, and volume over time (from nightly snapshots).

Param	Type	Default	Description
`days`	int	90	Days of history (1-365)

Returns { painSignalId, points: [{date, ownerCount, score, volume}], trackingStartedAt }.

GET /api/pain-signals/{id}/evidence

Paginated evidence items (developer quotes with source metadata).

Param	Type	Default	Description
`page`	int	0	Page number
`size`	int	20	Page size (max 100)

EvidenceItem fields:

Field	Type	Description
`chunkId`	string	Chunk ID
`documentId`	string	Source document ID
`painSignalId`	string	Signal UUID
`provider`	string	Source platform (e.g. `github`, `stackoverflow`)
`postTitle`	string	Post title (nullable)
`externalId`	string	Original external post ID
`createdAt`	ISO instant	Chunk assignment timestamp

curl "https://api.echosift.io/api/pain-signals/SIGNAL_UUID/evidence?page=0&size=20" \
  -H "Authorization: Bearer es_YOUR_KEY_HERE"

GET /api/pain-signals/{id}/sources

Provider distribution for a signal.

Param	Type	Default	Description
`cluster`	boolean	false	When true, aggregates across the similarity cluster

Returns SourceDistribution[]:

Field	Type	Description
`provider`	string	Source platform name
`count`	long	Mention count
`percentage`	double	Share of total [0-100]

GET /api/pain-signals/{id}/brief

Read-only access to an existing opportunity brief. Returns 404 when no brief has been generated or the brief is stale (older than 7 days).

See the get_brief MCP tool for the full field reference.

GET /api/pain-signals/timelines

Batch timeline (sparklines) for multiple signals in one request.

Param	Type	Required	Description
`ids`	string	yes	Comma-separated signal UUIDs (max 50)
`days`	int	no	Days of history (1-365, default 30)

Returns BatchTimelineItem[]:

Field	Type	Description
`painSignalId`	string	Signal UUID
`buckets`	TimelineBucket[]	Daily mention buckets (zeros omitted)

Semantic Search

GET /api/signals/semantic-search

Semantic search over the full signal corpus. Returns signals ranked by relevance to the query.

Param	Type	Required	Description
`q`	string	yes	Search query (3-500 chars)
`limit`	int	no	Max results (1-50, default 20)