API Reference

Authentication boundaries Product operations use a Supabase user session bearer.
Raw export accepts an export-scoped cl_live_* key for accounts with raw export enabled by CrowdListen.
Key management always requires the user session bearer, never an API key. Start with the authentication and key permissions guide. These examples cover common workflows; the complete API catalogue includes all deployed operations, request schemas and responses. Live OpenAPI JSON Live Swagger UI

Product API

These are the same authenticated operations used by the CrowdListen web product. Obtain a Supabase access token through sign-in and send it as the bearer token. Check service health at /agent/v1/health. Discover saved workflows at /api/entities/{entity_id}/skills. Before a run, read /api/entities/{entity_id}/skills/{skill_id}/quote?source_mode=refresh, review its estimated credits and maximum, then submit the approved scope_hash and max_charge_credits to the workflow runs endpoint with an Idempotency-Key. A connection response of scope_required asks for an entity_id or project_id; it does not ask for a broader API-key permission. POST/agent/v1/analysis/run Start an analysis and stream progress, evidence, and the final result over the response body. Caller identity is always derived from the verified bearer. Auth: Supabase user session bearer

Parameters

Name Type Required Description question string required Research question, 1–1000 characters project_id uuid optional Project that owns the analysis search_mode string optional knowledge, multi_source, web_only, user_only, or user_first platforms string[] optional reddit, twitter, github, or news entity_id uuid optional Optional tracked-entity scope depth string optional brief or deep

Examples

cURL

curl -N -X POST https://agent.crowdlisten.com/agent/v1/analysis/run \
  -H "Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question":"What are developers saying about inference latency?","search_mode":"multi_source","platforms":["reddit","github"]}'

Response

event: progress
data: {"step":"discovery","status":"running","progress":20}

event: result
data: {"analysis_id":"uuid","status":"completed","data":{...}}

POST/agent/v1/search Discover source-backed public evidence without running synthesis. Provider failures return 502 or 503 rather than an empty success. Auth: Supabase user session bearer

Parameters

Name Type Required Description query string required Search query, up to 2000 characters platforms string[] optional Optional platform filter limit integer optional 1–200 results date_from string optional Optional ISO date floor

Examples

cURL

curl -X POST https://agent.crowdlisten.com/agent/v1/search \
  -H "Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"Fireworks AI developer feedback","platforms":["reddit","github"],"limit":20}'

Response

{
  "results": [{"title":"...","url":"https://...","platform":"reddit","snippet":"..."}],
  "count": 1,
  "query": "Fireworks AI developer feedback"
}

GET/agent/v1/context/recall Search the signed-in user’s saved pages with hybrid keyword and vector retrieval. Auth: Supabase user session bearer

Parameters

Name Type Required Description query string required Recall query limit integer optional 1–20 results project_id uuid optional Optional project scope

Examples

cURL

curl "https://agent.crowdlisten.com/agent/v1/context/recall?query=pricing+objections&limit=5" \
  -H "Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN"

POST/agent/v1/context/save Create or replace a page at a stable user-scoped path. Auth: Supabase user session bearer

Parameters

Name Type Required Description title string required Page title content string required Page content, up to 500,000 characters path string optional Stable page path tags string[] optional Page tags project_id uuid optional Optional project scope

Examples

cURL

curl -X POST https://agent.crowdlisten.com/agent/v1/context/save \
  -H "Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Pricing objections","path":"research/pricing-objections","content":"Evidence...","tags":["sales"]}'

Raw Export

Export is intended for accounts with raw export enabled by CrowdListen and internal agents that need full-fidelity rows rather than a small recall result. GET/agent/v1/export/completeness Audit text, URL, enrichment, and platform coverage before treating a corpus as comprehensive. Auth: Whitelisted user JWT, or cl_live_* key with export scope

Parameters

Name Type Required Description entity_id uuid optional Tracked entity scope workspace_id uuid optional Workspace scope platform string optional Platform filter

Examples

cURL

curl "https://agent.crowdlisten.com/agent/v1/export/completeness?entity_id=ENTITY_UUID" \
  -H "Authorization: Bearer cl_live_xxx"

GET/agent/v1/export/table/{table_name} Page through allowed raw tables: entities, content_store, opinion_units, entity_insights, insight_evidence, pages, and knowledge. Auth: cl_live_* key with export scope

Parameters

Name Type Required Description table_name string required Allowed table name entity_id uuid optional Tracked entity scope limit integer optional Page size, up to 5000 offset integer optional Pagination offset

Examples

cURL

curl "https://agent.crowdlisten.com/agent/v1/export/table/content_store?entity_id=ENTITY_UUID&limit=5000" \
  -H "Authorization: Bearer cl_live_xxx"

Key Management

Keys currently support ingest, export, or *. New keys default to ingest only; explicitly choose export for reading raw records or both key scopes when required. At least one scope is required. The raw key is returned once. Keys belong to your account, not to the workspace currently selected in the browser. Ordinary agent login uses your user session and does not require a key. POST/api/user/keys Create a scoped API key. Auth: Supabase user session bearer

Parameters

Name Type Required Description name string required Human-readable key name scopes string[] optional ingest, export, or *; defaults to [“ingest”]. An explicit empty list is rejected.

Examples

cURL

curl -X POST https://agent.crowdlisten.com/api/user/keys \
  -H "Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Export agent","scopes":["export"]}'

Response

{
  "key": {"id":"uuid","name":"Export agent","key_prefix":"cl_live_ab12cd","scopes":["export"],"is_active":true},
  "raw_key": "cl_live_..."
}

GET/api/user/keys List masked keys owned by the signed-in user. Auth: Supabase user session bearer DELETE/api/user/keys/{key_id} Revoke a key owned by the signed-in user. Auth: Supabase user session bearer GET/api/user/keys/{key_id}/usage Read stored usage records for one owned key. Auth: Supabase user session bearer

Get started

Work with experts

Build

Updates

Product API

Parameters

Examples

Response

Parameters

Examples

Response

Parameters

Examples

Parameters

Examples

Raw Export

Parameters

Examples

Parameters

Examples

Key Management

Parameters

Examples

Response

​Product API

​Parameters

​Examples

​Response

​Parameters

​Examples

​Response

​Parameters

​Examples

​Parameters

​Examples

​Raw Export

​Parameters

​Examples

​Parameters

​Examples

​Key Management

​Parameters

​Examples

​Response

Product API

Parameters

Examples

Response

Parameters

Examples

Response

Parameters

Examples

Parameters

Examples

Raw Export

Parameters

Examples

Parameters

Examples

Key Management

Parameters

Examples

Response