KOLens Alerts API

The Alerts API from KOLens — 6 operation(s) for alerts.

GitHub OpenAPI

Operations 7

GET /api/alerts List Alerts #
POST /api/alerts/{alert_id}/read Mark Alert Read #
POST /api/alerts/bulk-read Bulk Mark Read #
POST /api/alerts/detect-now Detect Now #
GET /api/alert-preferences Get Alert Preferences #
PUT /api/alert-preferences Upsert Alert Preferences #
POST /api/alert-preferences/test Test Alert Preferences #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/kolens-ai:kolens-ai-alerts-api"
All apis
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.

Get an API 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 Specification

kolens-ai-alerts-api-openapi.yml Raw ↑
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