Clerk
API Reference
Programmatic access to deep research. All endpoints prefixed /api/v1 with Bearer auth.
/api/v1/researchCreate a research task. Body: { topic, timeframe, options }.
202 Accepted → { research_id, status: "queued", estimated_duration: "7 days" }
/api/v1/research/{id}Get research task details, status, and progress (completed/total niches).
200 → { topic, status: "extraction", progress: { completed_niches: 42, total_niches: 100 } }
/api/v1/research/{id}/statisticsAggregate statistics: reliability, sentiment distribution, odds, trend vectors.
200 → { avg_reliability_score, sentiment_distribution, odds_calculations }
/api/v1/research/{id}/correlationsCorrelation matrix across sub-niches (e.g., layer2_scaling ↔ defi_tvl).
200 → { matrix: { layer2_scaling: { defi_tvl: 0.82 } } }
/api/v1/research/{id}/reportDownload the S-Rank report. Format: pdf | markdown | html.
200 → report file with correct Content-Type
/api/v1/research/{id}/downloadDownload all research data as a ZIP. Format: json | parquet | csv.
200 → ZIP containing full research data
/api/v1/research/{id}/nichesList all sub-niches with status and reliability scores.
200 → { items: [...], total: 100 }
/api/v1/configSystem configuration: max_workers, niches_per_topic, allowed timeframes.
200 → { max_workers: 100, niches_per_topic: 100 }
WebSocket — Real-Time Updates
Connect to WS /ws/research/{research_id} to stream live research progress.
niche_completed
{ niche_id, reliability_score, sentiment }
niche_failed
{ niche_id, error }
progress_update
{ completed, total }
phase_change
{ phase: "analysis" }
completed
{ report_url }