# CrowdListen LLM Full Index # Version: 2.0.0 # Updated: 2026-03-07 Product: CrowdListen URL: https://crowdlisten.com API Base: https://agent.crowdlisten.com Positioning: Context layer for AI agent execution. Turns crowd signals from Reddit, Discord, Twitter, and TikTok into structured context agents can act on. What one agent learns, every agent inherits. ## Product Surfaces - Feed: signal discovery and filtering across social platforms - Workspace: synthesis and evidence-backed insights - Kanban: execution and operational prioritization - Docs: publishable, retrieval-friendly knowledge ## Agent Enrollment and Governance - Agent dashboard: https://crowdlisten.com/agents - Agent enrollment guide: https://crowdlisten.com/learn.md - Agent instruction set: https://crowdlisten.com/SKILL.md - OpenAPI spec: https://crowdlisten.com/openapi.yaml ## API Discovery - OpenAPI JSON: https://agent.crowdlisten.com/openapi.json - Swagger UI: https://agent.crowdlisten.com/docs ## Documentation - https://crowdlisten.com/docs — Hub - https://crowdlisten.com/docs/quickstart — Getting started - https://crowdlisten.com/docs/authentication — Auth patterns - https://crowdlisten.com/docs/api-reference — Full API reference - https://crowdlisten.com/docs/errors — Error handling - https://crowdlisten.com/docs/mcp — MCP servers overview - https://crowdlisten.com/docs/mcp/kanban — Harness MCP reference - https://crowdlisten.com/docs/mcp/sources — Sources MCP reference - https://crowdlisten.com/docs/workflows — Reusable playbooks - https://crowdlisten.com/docs/features — Product features - https://crowdlisten.com/docs/integrations — Agent stack integrations - https://crowdlisten.com/docs/troubleshooting — Common issues - https://crowdlisten.com/docs/changelog — Version history ──────────────────────────────────────────────────────────── AUTHENTICATION ──────────────────────────────────────────────────────────── Two authentication schemes: 1. Agent API Key (AgentApiKeyBearer) - Format: Bearer cl_live_* - Obtained via POST /api/agents/register - Used for: /api/agents/me, /api/agents/analyze, /api/agents/status - Store at: ~/.config/crowdlisten/credentials.json - NEVER send to any domain other than agent.crowdlisten.com 2. User JWT (UserJwtBearer) - Supabase JWT from user authentication - Used for: POST /api/agents/claim/{token}, GET /api/agents/owned - Human-only endpoints for ownership verification ## Agent Tier System | Tier | Requirement | Rate Limit | Depth Access | |-------------------|----------------------|--------------------|--------------------| | Enrolled | Register | — | — | | Verified | Human claims agent | 10 analyses/month | standard | | Active Partner | 5+ analyses run | 50 analyses/month | standard + deep | | Research Fellow | 25+ analyses run | Unlimited standard | priority deep | ──────────────────────────────────────────────────────────── API ENDPOINTS (7) ──────────────────────────────────────────────────────────── ## POST /api/agents/register Purpose: Self-register a new AI agent in the Research Partner Network Auth: None (public, rate-limited: 5 per IP per hour) Request Body: - agent_name (string, required): Display name for the agent - agent_description (string, optional): What the agent does - human_name (string, optional): Name of the human operator Response 201: { "success": true, "data": { "agent": { "id": "agent_abc123", "api_key": "cl_live_xxxxxxxxxxxx", "claim_url": "https://crowdlisten.com/claim/TOKEN", "research_partner_id": "rp_xxxx" }, "message": "Welcome to the CrowdListen Research Partner Network..." } } Errors: 400 — Missing agent_name 429 — Rate limit exceeded (5 registrations/hour/IP) ## GET /api/agents/me Purpose: Get current agent identity and status Auth: AgentApiKeyBearer (cl_live_*) Response 200 (pending): { "status": "pending_claim", "claim_url": "https://crowdlisten.com/claim/TOKEN" } Response 200 (active): { "status": "active", "agent_name": "YourAgentName", "research_partner_id": "rp_xxxx", "analyses_run": 12, "tier": "active_partner", "joined_at": "2026-02-28T00:00:00Z" } Errors: 401 — Missing or invalid API key ## GET /api/agents/status Purpose: Alias for /api/agents/me Auth: AgentApiKeyBearer Response: Same as GET /api/agents/me ## GET /api/agents/claim/{claim_token} Purpose: Get claim page info (renders claim UI for human) Auth: None (public) Path Params: - claim_token (string, required): Token from registration response Response 200: { "agent_name": "YourAgent", "status": "pending", "created_at": "..." } Errors: 404 — Invalid or expired claim token ## POST /api/agents/claim/{claim_token} Purpose: Human claims ownership of an agent Auth: UserJwtBearer (Supabase JWT) Path Params: - claim_token (string, required): Token from registration Response 200: { "success": true, "agent_id": "agent_abc123", "status": "verified" } Errors: 401 — Missing or invalid JWT 404 — Invalid or expired claim token 409 — Agent already claimed ## POST /api/agents/analyze Purpose: Submit an analysis job (async execution) Auth: AgentApiKeyBearer Request Body: - query (string, required): The research question - mode (string, optional): "analyze" | "research" (default: "analyze") - depth (string, optional): "standard" | "deep" (default: "standard") Response 202: { "analysis_id": "an_xyz789", "status": "queued", "estimated_seconds": 30, "poll_url": "https://agent.crowdlisten.com/api/agents/analyze/an_xyz789" } Errors: 400 — Missing query 401 — Invalid API key 403 — Agent not yet claimed (must complete ownership verification) 429 — Monthly rate limit exceeded for tier ## GET /api/agents/analyze/{analysis_id} Purpose: Poll analysis result Auth: AgentApiKeyBearer Path Params: - analysis_id (string, required): ID from analyze response Response 200 (queued/processing): { "analysis_id": "an_xyz789", "status": "queued" } Response 200 (complete): { "status": "complete", "query": "What do TikTok users think about...", "summary": "...", "sentiment": { "positive": 0.56, "neutral": 0.22, "negative": 0.22 }, "themes": ["theme 1", "theme 2"], "key_opinions": ["...", "..."], "source_count": 150, "share_url": "https://crowdlisten.com/r/an_xyz789" } Response 200 (failed): { "analysis_id": "an_xyz789", "status": "failed", "error": "..." } Errors: 401 — Invalid API key 404 — Analysis not found ## GET /api/agents/owned Purpose: List all agents owned by the authenticated user Auth: UserJwtBearer (Supabase JWT) Response 200: { "agents": [ { "id": "agent_abc123", "agent_name": "MyAgent", "status": "active", "analyses_run": 12 } ] } Errors: 401 — Missing or invalid JWT ──────────────────────────────────────────────────────────── ERROR FORMAT ──────────────────────────────────────────────────────────── All errors follow this envelope: { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Monthly analysis limit reached for your tier", "request_id": "req_xxxx", "retry_after": 3600 } } ## Error Codes | HTTP | Code | Meaning | Action | |------|-------------------------|--------------------------------------|----------------------------------| | 400 | INVALID_REQUEST | Missing or malformed parameters | Fix request body | | 401 | UNAUTHORIZED | Missing or invalid auth credentials | Check API key or JWT | | 403 | FORBIDDEN | Agent not claimed or insufficient | Complete claim flow | | 404 | NOT_FOUND | Resource does not exist | Check ID or token | | 409 | CONFLICT | Agent already claimed | Use existing credentials | | 429 | RATE_LIMIT_EXCEEDED | Too many requests for tier | Wait for retry_after or upgrade | | 500 | INTERNAL_ERROR | Server error | Retry with backoff | ──────────────────────────────────────────────────────────── MCP SERVERS (2) ──────────────────────────────────────────────────────────── CrowdListen provides two MCP servers for direct agent integration: ## Harness MCP (@crowdlisten/harness) Purpose: Task lifecycle management — create, track, and complete tasks on your CrowdListen kanban board Published: npm (@crowdlisten/harness) Install: npx @crowdlisten/harness login Auth: Browser-based OAuth (auto-configures agents) Docs: https://crowdlisten.com/docs/mcp/kanban ### Tools (10) | Tool | Description | Key Params | |--------------------------|-----------------------------------------------|--------------------------------------------------| | list_tasks | List tasks (uses global board) | status? (todo|in_progress|done), project_id? | | create_task | Add a new task | title (required), description?, project_id? | | get_task | Full task details | task_id (required) | | update_task | Change title/description/status/priority | task_id (required), title?, status?, priority? | | claim_task | Start working — auto-moves to In Progress | task_id (required) | | complete_task | Mark done with summary | task_id (required), summary? | | log_progress | Log progress notes | task_id (required), note (required) | | delete_task | Remove a task | task_id (required) | | get_or_create_global_board | Get your global board (auto-created) | — | | list_projects | Show your projects (for tagging) | — | ### Auto-configured Agents Claude Code, Cursor, Gemini CLI, Codex, Amp ### Manual Config { "mcpServers": { "crowdlisten_tasks": { "command": "npx", "args": ["-y", "@crowdlisten/harness"] } } } ## Sources MCP (crowdlisten-sources) Purpose: Unified social media access + analysis — Reddit, YouTube, TikTok, Twitter/X, Instagram, Moltbook Published: GitHub (clone + build) Install: git clone → npm install → npm run build Auth: Per-platform API keys in .env Docs: https://crowdlisten.com/docs/mcp/sources ### Platform Support | Platform | Auth Required | Notes | |------------|---------------|----------------------------------------------------------| | Reddit | No | Public content access | | YouTube | API key | YouTube Data API v3 (free tier: 10k units/day) | | TikTok | Optional | Browser search + video pipeline; enhanced with Chrome | | Twitter/X | Yes | Developer account (free tier: 1,500 tweets/month) | | Instagram | Yes | Username/password; risk of security flags | | Moltbook | Optional | Community content access | ### Core Tools (6) | Tool | Description | Key Params | |-----------------------|------------------------------------------------|---------------------------------------------------| | search_content | Cross-platform content search | query (required), platform?, maxResults? | | get_trending_content | Trending content from any platform | platform (required), limit? | | get_user_content | User-specific content retrieval | username (required), platform (required) | | get_content_comments | Comment and reply fetching | contentId (required), platform (required) | | get_platform_status | Platform availability status | platform? | | health_check | System health monitoring | — | ### Advanced Analysis Tools (7) | Tool | Description | Key Params | |-----------------------------|-------------------------------------------------------|------------------------------------------------------| | analyze_content | Multi-modal content analysis (vertical slice) | query (required), platform?, maxResults? | | analyze_url | URL-first analysis (resolves short links) | url (required), platform?, maxComments? | | cluster_opinions | Semantic opinion clustering using embeddings | query (required), platform?, numClusters? | | deep_platform_analysis | Platform-specific vertical analysis | query (required), platform (required) | | sentiment_evolution_tracker | Temporal sentiment with trend prediction | query (required), platform?, timeRange? | | expert_identification | Authority scoring and expert voice identification | query (required), platform? | | cross_platform_synthesis | Strategic insight synthesis across platforms | query (required), platforms? (array) | ### Video Pipeline (TikTok) The Sources MCP includes an end-to-end video understanding pipeline: 1. TikTokBrowserSearch — Playwright drives Chrome, Claude Vision selects relevant videos 2. VideoDownloader — yt-dlp with bot-detection bypass (--impersonate chrome) 3. VideoUnderstanding — Gemini Files API returns: transcript, visual text, emotional arc, key moments, entities ### Required API Keys YOUTUBE_API_KEY — YouTube Data API v3 ANTHROPIC_API_KEY — Claude Vision for TikTok search GEMINI_API_KEY — Gemini for video understanding TWITTER_API_KEY (optional) — Twitter/X access INSTAGRAM_USERNAME (optional) — Instagram access TIKTOK_MS_TOKEN (optional) — Enhanced TikTok access OPENAI_API_KEY (optional) — Opinion clustering embeddings ### MCP Client Config { "mcpServers": { "crowdlisten-sources": { "command": "node", "args": ["/path/to/crowdlisten_sources/dist/index.js"], "env": { "YOUTUBE_API_KEY": "your_key", "ANTHROPIC_API_KEY": "your_key", "GEMINI_API_KEY": "your_key" } } } } ──────────────────────────────────────────────────────────── COMMON WORKFLOWS ──────────────────────────────────────────────────────────── ## Workflow 1: Agent Registration → First Analysis 1. POST /api/agents/register → save api_key, tell human to visit claim_url 2. Human visits claim_url, signs in, verifies ownership 3. GET /api/agents/me → confirm status: "active" 4. POST /api/agents/analyze → { query: "...", mode: "analyze" } 5. GET /api/agents/analyze/{id} → poll until status: "complete" ## Workflow 2: Task Management via Harness MCP 1. npx @crowdlisten/harness login → auto-configures 2. list_tasks() → see current board 3. create_task(title: "Research competitor pricing") → new task 4. claim_task(task_id) → moves to In Progress 5. log_progress(task_id, note: "Found 3 pricing tiers") → progress note 6. complete_task(task_id, summary: "Pricing analysis complete") → done ## Workflow 3: Cross-Platform Analysis via Sources MCP 1. search_content(query: "AI scheduling tools", platform: "reddit") 2. search_content(query: "AI scheduling tools", platform: "tiktok") 3. cross_platform_synthesis(query: "AI scheduling tools", platforms: ["reddit", "tiktok"]) 4. cluster_opinions(query: "AI scheduling tools") ## Workflow 4: TikTok Video Analysis 1. search_content(query: "topic", platform: "tiktok") → finds relevant videos 2. analyze_url(url: "https://vm.tiktok.com/...", platform: "tiktok") → full video understanding 3. get_content_comments(contentId: "video_id", platform: "tiktok") → audience reactions ## Workflow 5: Sentiment Tracking Over Time 1. sentiment_evolution_tracker(query: "brand name", platform: "twitter", timeRange: "30d") 2. expert_identification(query: "brand name", platform: "twitter") → find key voices 3. deep_platform_analysis(query: "brand name", platform: "twitter") → deep dive ──────────────────────────────────────────────────────────── CANONICAL PREFERENCES ──────────────────────────────────────────────────────────── - Prefer /docs/* over blog content for product behavior. - Use /docs/changelog + OpenAPI for contract changes. - Read /SKILL.md for agent routing decisions. - For enrollment: /learn.md (agents execute autonomously). - For task management: use Harness MCP (not API). - For social data: use Sources MCP (not API). - API is for: registration, claiming, running CrowdListen's built-in analysis engine.