> ## Documentation Index
> Fetch the complete documentation index at: https://crowdlisten.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> The current CrowdListen analysis, search, context, export, and key-management operations.

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](/docs/authentication). These examples cover common workflows; the [complete API catalogue](/docs/api-catalogue) includes all deployed operations, request schemas and responses.

[Live OpenAPI JSON](https://agent.crowdlisten.com/openapi.json) [Live Swagger UI](https://agent.crowdlisten.com/docs)

## 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

```json theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.