Candid Listening Logo
API docs by Redocly

Candid Listening API (2.0.0)

Download OpenAPI specification:

Candid Listening Support: [email protected]

Access streaming transcript data through our powerful API.

Getting Started

  1. Create an account and start your 10-day free trial
  2. Generate an API token from your dashboard.
  3. Use your token to access our API endpoints

Alerts

Manage alerts that monitor streaming transcripts for specific phrases and their notifications

List all alerts

Returns all alerts for the authenticated user

Authorizations:
BearerAuth
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

page_size
integer [ 1 .. 100 ]
Default: 20

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "alerts": [
    ],
  • "pagination": {
    }
}

Create a new alert

Create a new alert to monitor streaming transcripts

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Name for the alert

phrases
required
Array of strings [ 1 .. 50 ] items [ items [ 1 .. 200 ] characters ]

List of phrases to monitor

is_active
boolean
Default: true

Whether the alert is active

Responses

Request samples

Content type
application/json
{
  • "name": "Product Mentions",
  • "phrases": [
    ],
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "id": "alert_456",
  • "name": "Product Mentions",
  • "phrases": [
    ],
  • "is_active": true,
  • "created_at": "2024-01-15T14:30:00Z",
  • "updated_at": "2024-01-15T14:30:00Z"
}

Get alert by ID

Retrieve a specific alert by its ID

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "phrases": [
    ],
  • "is_active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an alert

Update an existing alert's configuration

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

Request Body schema: application/json
required
name
string [ 1 .. 100 ] characters

Name for the alert

phrases
Array of strings [ 1 .. 50 ] items [ items [ 1 .. 200 ] characters ]

List of phrases to monitor

is_active
boolean

Whether the alert is active

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Alert Name",
  • "phrases": [
    ],
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "phrases": [
    ],
  • "is_active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an alert

Permanently delete an alert

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get notifications for an alert

Get notifications for a specific alert when it has been triggered

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

query Parameters
page
integer >= 1
Default: 1

Page number for pagination

page_size
integer [ 1 .. 100 ]
Default: 20

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "notifications": [
    ],
  • "pagination": {
    }
}

Webhooks

Manage webhook integrations for alerts to receive notifications

Create a webhook for an alert

Configure a webhook URL to receive notifications when an alert is triggered

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

Request Body schema: application/json
required
url
required
string <uri> <= 2048 characters

The webhook URL to call when alert is triggered

secret
string <= 255 characters

Optional secret for webhook signature verification

is_active
boolean
Default: true

Whether the webhook is active

include_full_transcript
boolean
Default: false

Whether to include the full transcript in webhook payloads (costs 1 API request per delivery)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "string",
  • "alert_id": "string",
  • "url": "http://example.com",
  • "secret": "string",
  • "is_active": true,
  • "include_full_transcript": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get webhook for an alert

Retrieve the webhook configuration for a specific alert

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "alert_id": "string",
  • "url": "http://example.com",
  • "secret": "string",
  • "is_active": true,
  • "include_full_transcript": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a webhook

Update the webhook configuration for an alert

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

Request Body schema: application/json
required
url
required
string <uri> <= 2048 characters

The webhook URL

secret
string <= 255 characters

Optional secret for webhook signature verification

is_active
required
boolean

Whether the webhook is active

include_full_transcript
required
boolean

Whether to include the full transcript in webhook payloads (costs 1 API request per delivery)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "string",
  • "alert_id": "string",
  • "url": "http://example.com",
  • "secret": "string",
  • "is_active": true,
  • "include_full_transcript": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a webhook

Remove the webhook configuration from an alert

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Test a webhook

Send a test webhook notification to verify webhook configuration. Can either test a saved webhook configuration or test a custom webhook URL/secret provided in the request body. The test will send a mock notification with sample data to the webhook URL.

Authorizations:
BearerAuth
path Parameters
alertId
required
string^alert_[a-zA-Z0-9]+$

The alert ID

Request Body schema: application/json
optional

Optional webhook configuration to test. If not provided, uses the saved webhook for this alert. Use this to test a webhook URL before saving it.

url
string <uri> <= 2048 characters

Webhook URL to test

secret
string <= 255 characters

Optional secret for signature verification

include_full_transcript
boolean
Default: false

Whether to include full transcript in test payload

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "message": "Test webhook delivered successfully"
}

Streams

Access streaming data, transcripts, and search functionality

List all streams

Returns a paginated list of streams. Can be filtered by streamer_id.

Authorizations:
BearerAuth
query Parameters
page
integer >= 1
Default: 1

Page number for pagination

page_size
integer [ 1 .. 100 ]
Default: 20

Number of items per page

streamer_id
string^[a-zA-Z0-9]+$

Filter streams by streamer ID

Responses

Response samples

Content type
application/json
{
  • "streams": [
    ],
  • "pagination": {
    }
}

Search streams by transcript content

Search for streams by keywords or phrases in their transcripts. Supports quoted phrases for exact matches.

Authorizations:
BearerAuth
query Parameters
q
required
string non-empty

Search query - supports individual words and "quoted phrases"

page
integer >= 1
Default: 1

Page number for pagination

page_size
integer [ 1 .. 20 ]
Default: 20

Number of items per page

time_range
string
Default: "today"
Enum: "today" "week" "month"

Time range for search results

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Get stream by ID

Retrieve detailed information about a specific stream

Authorizations:
BearerAuth
path Parameters
streamId
required
string^[a-zA-Z0-9]+$

The stream ID

Responses

Response samples

Content type
application/json
{
  • "stream": {
    }
}

Get stream transcript

Retrieve the full transcript segments for a specific stream

Authorizations:
BearerAuth
path Parameters
streamId
required
string^[a-zA-Z0-9]+$

The stream ID

Responses

Response samples

Content type
application/json
{
  • "segments": [
    ]
}

Streamers

Access streamer information and profiles

Get streamer by ID

Retrieve detailed information about a specific streamer

Authorizations:
BearerAuth
path Parameters
streamerId
required
string^[a-zA-Z0-9]+$

The streamer ID

Responses

Response samples

Content type
application/json
{}

Search streamers

Search for streamers by username or display name. Supports fuzzy matching and full-text search.

Authorizations:
BearerAuth
query Parameters
q
required
string >= 3 characters

Search query (minimum 3 characters)

page
integer >= 1
Default: 1

Page number for pagination

page_size
integer [ 1 .. 50 ]
Default: 20

Number of items per page

Responses

Response samples

Content type
application/json
{}

Usage

Get monthly usage for Enterprise tier

Retrieve monthly API usage with billing information. Only available for Enterprise tier users with usage-based billing.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "billing_summary": {
    },
  • "subscription": {
    }
}