API Reference
All APIs are Next.js Route Handlers under src/app/api/. Authentication is enforced via Supabase JWT middleware on all routes except public ones.
Internal API Routes
Search & Analysis
| Endpoint | Method | Auth | Description | Max Duration |
|---|---|---|---|---|
/api/query | POST | Yes | Main search — direct or playbook mode | 60s |
/api/playbook | POST | Yes | Deep 4-lens analysis (SSE stream) | 120s |
/api/citations/search | GET | Yes | Citation lookup | — |
Threads
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/threads | GET/POST | Yes | List/create threads |
/api/threads/[id] | GET/PATCH | Yes | Get/update thread |
/api/threads/[id]/beliefs | GET/POST | Yes | Manage saved beliefs |
/api/threads/[id]/share | POST | Yes | Publish thread, get share URL |
/api/threads/top | GET | Yes | Popular community threads |
Graph & Analytics
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/graph/data | GET | Yes | Speaker nodes + similarity links (1h cache) |
/api/market | GET | Yes | BTC price + Fear & Greed index |
/api/feed | GET | Yes | Community cards (cursor-based pagination) |
Auth & Admin
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/auth/logout | POST | Yes | End session |
/auth/callback | GET | No | OAuth callback |
/api/invite/claim | POST | Yes | Claim beta invite code |
/api/alerts | GET/POST | Yes | Alert management |
/api/notifications | GET | Yes | User notifications |
/api/cron/check-alerts | GET | Cron | Daily alert check (8 AM) |
External Service APIs
| Service | Purpose | Auth |
|---|---|---|
| Supabase | DB, Auth, Storage | Anon key + Service role key |
| Qdrant Cloud | Vector similarity search | API key header |
| OpenAI (GPT-4o) | Query synthesis + analysis | API key |
| OpenAI (Embeddings) | text-embedding-3-large | API key |
| DeepSeek | Optional reasoning model | API key |
| Tavily | Web search for Jackal (planned) | API key |
| HuggingFace | Dataset sync | HF token |
MCP Server
The project includes a Model Context Protocol server for use with Claude Desktop, Cursor, and other MCP clients.
10 Tools Available:
| Tool | Description |
|---|---|
search_transcripts | Semantic search over transcript chunks |
get_episode_context | Window around a timestamp |
get_speaker_turns | All speaking turns in an episode |
get_episode_summary | Episode metadata |
semantic_search | Exploratory vector search |
search_beliefs | Beliefs by speaker/topic |
get_timeline | Temporal distribution |
get_sentiment | Sentiment analysis |
compare_speakers | Compare perspectives |
get_similar_speakers | Co-occurrence clustering |
Run locally:
npm run mcp:build && node dist/mcp/server.js
# or with inspector
npm run mcp:inspect
Uses DuckDB in-memory with parquet files for fast local queries.