KOLens Alerts API
The Alerts API from KOLens — 6 operation(s) for alerts.
The Alerts API from KOLens — 6 operation(s) for alerts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/kolens-ai:kolens-ai-alerts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: KOLens Alerts API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: Alerts
paths:
/api/alerts:
get:
tags:
- Alerts
summary: List Alerts
operationId: list_alerts_api_alerts_get
security:
- HTTPBearer: []
parameters:
- name: type
in: query
required: false
schema:
anyOf:
- enum:
- rising_kol
- trending_video
- audience_drift
- comment_keyword
type: string
- type: 'null'
title: Type
- name: unread
in: query
required: false
schema:
type: boolean
default: false
title: Unread
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Limit
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GrowthAlertList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/alerts/{alert_id}/read:
post:
tags:
- Alerts
summary: Mark Alert Read
operationId: mark_alert_read_api_alerts__alert_id__read_post
security:
- HTTPBearer: []
parameters:
- name: alert_id
in: path
required: true
schema:
type: string
title: Alert Id
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MarkReadResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/alerts/bulk-read:
post:
tags:
- Alerts
summary: Bulk Mark Read
description: 'Mark several alerts read/unread in one call.
Powers multi-select on the /alerts feed. Scoped exactly like the
single-row route — the caller can only flip alerts they''re allowed
to see, so an attacker passing someone else''s id just no-ops (it
won''t match the WHERE clause). Returns how many rows actually
changed owner-side so the UI can reconcile its optimistic update.'
operationId: bulk_mark_read_api_alerts_bulk_read_post
security:
- HTTPBearer: []
parameters:
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkReadRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BulkReadResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/alerts/detect-now:
post:
tags:
- Alerts
summary: Detect Now
description: Run the growth detector synchronously for the calling api_key.
operationId: detect_now_api_alerts_detect_now_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DetectNowResponse'
security:
- HTTPBearer: []
/api/alert-preferences:
get:
tags:
- Alerts
summary: Get Alert Preferences
operationId: get_alert_preferences_api_alert_preferences_get
security:
- HTTPBearer: []
parameters:
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AlertPreferenceOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Alerts
summary: Upsert Alert Preferences
operationId: upsert_alert_preferences_api_alert_preferences_put
security:
- HTTPBearer: []
parameters:
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AlertPreferenceIn'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AlertPreferenceOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/alert-preferences/test:
post:
tags:
- Alerts
summary: Test Alert Preferences
description: 'Fire a synthetic alert through every enabled channel.
Returns the per-channel success/error map so the settings UI can
show the user what worked and what didn''t. The synthetic alert is
NOT persisted — this is a dry-run probe, not a real signal.
``channel`` lets the settings UI fire ONE channel at a time —
clicking "Test email" should not also POST to the user''s webhook
(which would noise up their Slack channel for no reason). Implemented
by temporarily disabling the other channel on the in-memory prefs
row before calling ``deliver_alert`` and restoring afterwards, so
the dispatcher logic stays untouched and the saved row is unchanged.
UX: when no preferences row exists yet, we upsert one from the
body (treating Test as Save+Test). This lets the user paste a
webhook URL and immediately click Test without first hitting
Save — the previous "save preferences first?" 404 was a confusing
dead end.'
operationId: test_alert_preferences_api_alert_preferences_test_post
security:
- HTTPBearer: []
parameters:
- name: channel
in: query
required: false
schema:
anyOf:
- type: string
pattern: ^(email|webhook)$
- type: 'null'
description: Restrict the probe to a single channel. Omit to test all enabled channels.
title: Channel
description: Restrict the probe to a single channel. Omit to test all enabled channels.
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AlertPreferenceIn'
default: {}
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Test Alert Preferences Api Alert Preferences Test Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
GrowthAlertOut:
properties:
id:
type: string
title: Id
alert_type:
type: string
enum:
- rising_kol
- trending_video
- audience_drift
- comment_keyword
title: Alert Type
subject_username:
anyOf:
- type: string
- type: 'null'
title: Subject Username
subject_video_id:
anyOf:
- type: string
- type: 'null'
title: Subject Video Id
score:
type: number
title: Score
payload:
anyOf:
- type: object
- type: 'null'
title: Payload
is_read:
type: boolean
title: Is Read
created_at:
type: string
title: Created At
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
trigger:
anyOf:
- type: object
- type: 'null'
title: Trigger
identity:
anyOf:
- $ref: '#/components/schemas/AlertIdentity'
- type: 'null'
type: object
required:
- id
- alert_type
- subject_username
- subject_video_id
- score
- payload
- is_read
- created_at
title: GrowthAlertOut
AlertPreferenceIn:
properties:
email_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Email Enabled
email_to:
anyOf:
- type: string
maxLength: 255
- type: 'null'
title: Email To
webhook_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Webhook Enabled
webhook_url:
anyOf:
- type: string
maxLength: 1024
- type: 'null'
title: Webhook Url
webhook_secret:
anyOf:
- type: string
maxLength: 128
- type: 'null'
title: Webhook Secret
muted_types:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Muted Types
rate_per_hour:
anyOf:
- type: integer
maximum: 1000.0
minimum: 0.0
- type: 'null'
title: Rate Per Hour
preferred_locale:
anyOf:
- type: string
maxLength: 10
- type: 'null'
title: Preferred Locale
description: 'BCP-47 tag from the supported set: en | zh-CN | ja'
rising_score_threshold:
anyOf:
- type: number
maximum: 100.0
minimum: 0.0
- type: 'null'
title: Rising Score Threshold
rising_follower_pct:
anyOf:
- type: number
maximum: 100.0
minimum: 0.0
- type: 'null'
title: Rising Follower Pct
rising_follower_delta:
anyOf:
- type: integer
maximum: 100000000.0
minimum: 0.0
- type: 'null'
title: Rising Follower Delta
rising_view_growth_pct:
anyOf:
- type: number
maximum: 10000.0
minimum: 0.0
- type: 'null'
title: Rising View Growth Pct
rising_lookback_days:
anyOf:
- type: integer
maximum: 365.0
minimum: 1.0
- type: 'null'
title: Rising Lookback Days
type: object
title: AlertPreferenceIn
description: 'Patch shape for PUT — every field optional. We diff vs the row
we already have so partial updates from the settings form don''t
accidentally clear a sibling field.'
BulkReadResponse:
properties:
updated:
type: integer
title: Updated
is_read:
type: boolean
title: Is Read
type: object
required:
- updated
- is_read
title: BulkReadResponse
AlertIdentity:
properties:
username:
type: string
title: Username
display_name:
anyOf:
- type: string
- type: 'null'
title: Display Name
avatar_url:
anyOf:
- type: string
- type: 'null'
title: Avatar Url
verified:
type: boolean
title: Verified
default: false
follower_count:
anyOf:
- type: integer
- type: 'null'
title: Follower Count
avg_views:
anyOf:
- type: number
- type: 'null'
title: Avg Views
avg_engagement_rate:
anyOf:
- type: number
- type: 'null'
title: Avg Engagement Rate
platform:
anyOf:
- type: string
- type: 'null'
title: Platform
avatar_url_cached:
anyOf:
- type: string
- type: 'null'
title: Avatar Url Cached
type: object
required:
- username
title: AlertIdentity
description: 'KOL identity attached to a rising_kol / trending_video alert so the
/alerts feed can render the shared rich KOLCard (avatar + nickname +
follower/views/engagement stats) without a per-row follow-up request
(Issue #4). ``None`` on the alert when no canonical ``DBAuthor`` row
exists for the subject (legacy / never-scraped handle).
The stat fields below (``follower_count`` … ``avatar_url_cached``) are
additive/optional — back-compat for any caller still reading only the
original identity shape — and feed the shared ``KOLCard`` on the web
alerts surface so it matches the rest of the app.'
MarkReadResponse:
properties:
id:
type: string
title: Id
is_read:
type: boolean
title: Is Read
type: object
required:
- id
- is_read
title: MarkReadResponse
BulkReadRequest:
properties:
ids:
items:
type: string
type: array
maxItems: 500
minItems: 1
title: Ids
is_read:
type: boolean
title: Is Read
default: true
type: object
required:
- ids
title: BulkReadRequest
description: 'Mark several alerts read/unread in one call (multi-select on the
/alerts feed). ``is_read`` defaults to True so the common
"mark selected as read" path can omit it.'
GrowthAlertList:
properties:
total:
type: integer
title: Total
unread:
type: integer
title: Unread
alerts:
items:
$ref: '#/components/schemas/GrowthAlertOut'
type: array
title: Alerts
type: object
required:
- total
- unread
- alerts
title: GrowthAlertList
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
DetectNowResponse:
properties:
api_key_hint:
type: string
title: Api Key Hint
description: First 8 chars of the api key.
alerts_generated:
type: integer
title: Alerts Generated
type: object
required:
- api_key_hint
- alerts_generated
title: DetectNowResponse
AlertThresholdDefaults:
properties:
rising_follower_pct:
type: number
title: Rising Follower Pct
rising_follower_delta:
type: integer
title: Rising Follower Delta
rising_view_growth_pct:
type: number
title: Rising View Growth Pct
rising_lookback_days:
type: integer
title: Rising Lookback Days
rising_score_threshold:
anyOf:
- type: number
- type: 'null'
title: Rising Score Threshold
type: object
required:
- rising_follower_pct
- rising_follower_delta
- rising_view_growth_pct
- rising_lookback_days
title: AlertThresholdDefaults
description: 'The global config defaults for the configurable rising_kol
thresholds (#661). Echoed alongside the per-user overrides so the
settings UI can show "default: 5%" placeholders and reset-to-default
affordances without hardcoding the numbers in the frontend.'
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AlertPreferenceOut:
properties:
email_enabled:
type: boolean
title: Email Enabled
email_to:
anyOf:
- type: string
- type: 'null'
title: Email To
webhook_enabled:
type: boolean
title: Webhook Enabled
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
webhook_secret:
anyOf:
- type: string
- type: 'null'
title: Webhook Secret
muted_types:
items:
type: string
type: array
title: Muted Types
rate_per_hour:
type: integer
title: Rate Per Hour
preferred_locale:
anyOf:
- type: string
- type: 'null'
title: Preferred Locale
supported_locales:
items:
type: string
type: array
title: Supported Locales
rising_score_threshold:
anyOf:
- type: number
- type: 'null'
title: Rising Score Threshold
rising_follower_pct:
anyOf:
- type: number
- type: 'null'
title: Rising Follower Pct
rising_follower_delta:
anyOf:
- type: integer
- type: 'null'
title: Rising Follower Delta
rising_view_growth_pct:
anyOf:
- type: number
- type: 'null'
title: Rising View Growth Pct
rising_lookback_days:
anyOf:
- type: integer
- type: 'null'
title: Rising Lookback Days
threshold_defaults:
anyOf:
- $ref: '#/components/schemas/AlertThresholdDefaults'
- type: 'null'
last_delivered_at:
anyOf:
- type: string
- type: 'null'
title: Last Delivered At
last_email_error:
anyOf:
- type: string
- type: 'null'
title: Last Email Error
last_webhook_error:
anyOf:
- type: string
- type: 'null'
title: Last Webhook Error
type: object
required:
- email_enabled
- webhook_enabled
- rate_per_hour
title: AlertPreferenceOut
securitySchemes:
HTTPBearer:
type: http
scheme: bearer