KOLens Watchlist API

The Watchlist API from KOLens — 3 operation(s) for watchlist.

GitHub OpenAPI

Operations 4

GET /api/watchlist List Watchlist #
POST /api/watchlist Add Watchlist #
DELETE /api/watchlist/{username} Remove Watchlist #
PUT /api/watchlist/{username}/audience Update Watchlist Audience Prefs #

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-watchlist-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-watchlist-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: KOLens Watchlist API
  description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
  version: 1.0.0
tags:
- name: Watchlist
paths:
  /api/watchlist:
    get:
      tags:
      - Watchlist
      summary: List Watchlist
      description: 'Return the user''s watchlist as a single significance-ranked change

        digest.


        One call yields everything the watchlist UI needs: per-entry identity,

        current stats, 7d/30d snapshot deltas, recent activity events, the

        "what changed" signal badges, a cached LLM activity summary if present,

        and a 0-100 significance score + tier. ``entries`` is sorted by

        ``significance.score`` descending — the most-changed creator first.


        No ``?signals=`` flag any more: the digest IS the response. The

        frontend must not fan out to ``GET /api/kols/{username}`` per row.'
      operationId: list_watchlist_api_watchlist_get
      security:
      - HTTPBearer: []
      parameters:
      - name: x-kolens-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Kolens-User-Id
      - name: x-kolens-workspace-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Kolens-Workspace-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistDigestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Watchlist
      summary: Add Watchlist
      description: 'Idempotent: re-adding an existing (user, username, platform) returns the existing row.


        ``platform`` defaults to ``"tiktok"`` so legacy callers (web Star

        button, plugin) keep working unchanged. The same handle on a

        different platform is a separate row — the unique index is

        (user_id, username, platform).'
      operationId: add_watchlist_api_watchlist_post
      security:
      - HTTPBearer: []
      parameters:
      - name: x-kolens-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Kolens-User-Id
      - name: x-kolens-workspace-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Kolens-Workspace-Id
      - name: x-kolens-locale
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Kolens-Locale
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistAdd'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistEntryOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/watchlist/{username}:
    delete:
      tags:
      - Watchlist
      summary: Remove Watchlist
      description: 'Remove a (user, username, platform) row from the watchlist.


        ``?platform=`` is a query parameter; default is ``"tiktok"`` so

        legacy clients that pass no platform keep deleting the TikTok row.

        Idempotent — delete-of-nonexistent is a no-op (returns 204).'
      operationId: remove_watchlist_api_watchlist__username__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
          title: Username
      - name: platform
        in: query
        required: false
        schema:
          type: string
          default: tiktok
          title: Platform
      - name: x-kolens-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Kolens-User-Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/watchlist/{username}/audience:
    put:
      tags:
      - Watchlist
      summary: Update Watchlist Audience Prefs
      description: 'AP-4: per-row audience auto-refresh prefs.


        PATCH-style — only the fields present in the body are touched.

        Sample size must be one of the priced tiers (200 / 500 / 2000) so

        the scheduler always knows what to charge.'
      operationId: update_watchlist_audience_prefs_api_watchlist__username__audience_put
      security:
      - HTTPBearer: []
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
          title: Username
      - 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/WatchlistAudiencePrefs'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistEntryOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ActivitySummaryOut:
      properties:
        period:
          type: string
          title: Period
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
        highlights:
          items:
            type: string
          type: array
          title: Highlights
          default: []
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated At
      type: object
      required:
      - period
      title: ActivitySummaryOut
      description: The cached LLM ``DBKolActivitySummary`` for this KOL, if one exists.
    ChangeWindowOut:
      properties:
        window_days:
          type: integer
          title: Window Days
        snapshots_count:
          type: integer
          title: Snapshots Count
        follower_delta:
          anyOf:
          - type: integer
          - type: 'null'
          title: Follower Delta
        follower_delta_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Follower Delta Pct
        avg_views_delta:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Views Delta
        avg_views_delta_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Views Delta Pct
        avg_views_unreliable:
          type: boolean
          title: Avg Views Unreliable
          default: false
        engagement_rate_delta:
          anyOf:
          - type: number
          - type: 'null'
          title: Engagement Rate Delta
      type: object
      required:
      - window_days
      - snapshots_count
      title: ChangeWindowOut
      description: Snapshot-derived deltas over one time window (7d or 30d).
    WatchlistDigestSummary:
      properties:
        total:
          type: integer
          title: Total
        n_act_now:
          type: integer
          title: N Act Now
        n_notable:
          type: integer
          title: N Notable
        n_quiet:
          type: integer
          title: N Quiet
        n_new_viral_videos:
          type: integer
          title: N New Viral Videos
        n_newly_dormant:
          type: integer
          title: N Newly Dormant
        total_unseen:
          type: integer
          title: Total Unseen
      type: object
      required:
      - total
      - n_act_now
      - n_notable
      - n_quiet
      - n_new_viral_videos
      - n_newly_dormant
      - total_unseen
      title: WatchlistDigestSummary
      description: 'Top-level roll-up — answers "what changed across my watchlist?"

        in seven integers so the UI can render a header without scanning

        every entry.'
    IdentityOut:
      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
      type: object
      required:
      - username
      title: IdentityOut
    VideoBriefOut:
      properties:
        video_id:
          type: string
          title: Video Id
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        thumbnail_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail Url
        caption:
          anyOf:
          - type: string
          - type: 'null'
          title: Caption
        views:
          anyOf:
          - type: integer
          - type: 'null'
          title: Views
        likes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Likes
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        is_sponsored:
          type: boolean
          title: Is Sponsored
          default: false
        is_ad:
          type: boolean
          title: Is Ad
          default: false
      type: object
      required:
      - video_id
      title: VideoBriefOut
    ChangesOut:
      properties:
        windows:
          additionalProperties:
            $ref: '#/components/schemas/ChangeWindowOut'
          type: object
          title: Windows
          default: {}
        recent_events:
          items:
            $ref: '#/components/schemas/ActivityEventOut'
          type: array
          title: Recent Events
          default: []
        activity_summary:
          anyOf:
          - $ref: '#/components/schemas/ActivitySummaryOut'
          - type: 'null'
      type: object
      title: ChangesOut
    WatchlistEntryOut:
      properties:
        id:
          type: string
          title: Id
        user_id:
          type: string
          title: User Id
        username:
          type: string
          title: Username
        platform:
          type: string
          title: Platform
          default: tiktok
        added_at:
          type: string
          title: Added At
        last_refreshed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Refreshed At
        next_refresh_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Refresh At
        is_paused:
          type: boolean
          title: Is Paused
        audience_auto_refresh:
          type: boolean
          title: Audience Auto Refresh
          default: false
        audience_refresh_interval_days:
          type: integer
          title: Audience Refresh Interval Days
          default: 7
        audience_sample_size:
          type: integer
          title: Audience Sample Size
          default: 200
        audience_last_refreshed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Audience Last Refreshed At
      type: object
      required:
      - id
      - user_id
      - username
      - added_at
      - is_paused
      title: WatchlistEntryOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SignalOut:
      properties:
        kind:
          type: string
          title: Kind
        severity:
          type: string
          title: Severity
        label:
          type: string
          title: Label
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
        data:
          anyOf:
          - type: object
          - type: 'null'
          title: Data
      type: object
      required:
      - kind
      - severity
      - label
      title: SignalOut
      description: One badge worth of "something changed since last check".
    CurrentStatsOut:
      properties:
        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
      type: object
      title: CurrentStatsOut
    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
    WatchlistAudiencePrefs:
      properties:
        audience_auto_refresh:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Audience Auto Refresh
        audience_refresh_interval_days:
          anyOf:
          - type: integer
            maximum: 90.0
            minimum: 1.0
          - type: 'null'
          title: Audience Refresh Interval Days
        audience_sample_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Audience Sample Size
      type: object
      title: WatchlistAudiencePrefs
      description: 'PATCH-shape for ``PUT /api/watchlist/{username}/audience``.


        All fields optional so the front-end toggle can flip just

        ``audience_auto_refresh`` without re-sending the others.'
    WatchlistEntryDigest:
      properties:
        id:
          type: string
          title: Id
        added_at:
          type: string
          title: Added At
        is_paused:
          type: boolean
          title: Is Paused
        platform:
          type: string
          title: Platform
          default: tiktok
        audience_auto_refresh:
          type: boolean
          title: Audience Auto Refresh
          default: false
        audience_refresh_interval_days:
          type: integer
          title: Audience Refresh Interval Days
          default: 7
        audience_sample_size:
          type: integer
          title: Audience Sample Size
          default: 200
        audience_last_refreshed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Audience Last Refreshed At
        identity:
          $ref: '#/components/schemas/IdentityOut'
        current:
          $ref: '#/components/schemas/CurrentStatsOut'
        changes:
          $ref: '#/components/schemas/ChangesOut'
        signals:
          items:
            $ref: '#/components/schemas/SignalOut'
          type: array
          title: Signals
          default: []
        latest_video:
          anyOf:
          - $ref: '#/components/schemas/VideoBriefOut'
          - type: 'null'
        days_since_last_post:
          anyOf:
          - type: integer
          - type: 'null'
          title: Days Since Last Post
        outreach:
          anyOf:
          - $ref: '#/components/schemas/OutreachBriefOut'
          - type: 'null'
        recommendation_score:
          anyOf:
          - type: integer
          - type: 'null'
          title: Recommendation Score
        significance:
          $ref: '#/components/schemas/SignificanceOut'
        unseen:
          type: boolean
          title: Unseen
          default: false
      type: object
      required:
      - id
      - added_at
      - is_paused
      - identity
      - current
      - changes
      - significance
      title: WatchlistEntryDigest
      description: One watched KOL, fully change-oriented — no per-row follow-up call.
    SignificanceOut:
      properties:
        score:
          type: integer
          title: Score
        tier:
          type: string
          title: Tier
        reasons:
          items:
            type: string
          type: array
          title: Reasons
          default: []
      type: object
      required:
      - score
      - tier
      title: SignificanceOut
    WatchlistAdd:
      properties:
        username:
          type: string
          maxLength: 100
          minLength: 1
          title: Username
        platform:
          type: string
          maxLength: 20
          minLength: 1
          title: Platform
          default: tiktok
      type: object
      required:
      - username
      title: WatchlistAdd
    OutreachBriefOut:
      properties:
        conversation_id:
          type: string
          title: Conversation Id
        status:
          type: string
          title: Status
        last_event_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Event At
        days_since_last_event:
          anyOf:
          - type: integer
          - type: 'null'
          title: Days Since Last Event
        event_count:
          type: integer
          title: Event Count
          default: 0
      type: object
      required:
      - conversation_id
      - status
      title: OutreachBriefOut
    ActivityEventOut:
      properties:
        id:
          type: string
          title: Id
        kind:
          type: string
          title: Kind
        summary:
          anyOf:
          - type: object
          - type: 'null'
          title: Summary
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        seen_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Seen At
        unseen:
          type: boolean
          title: Unseen
          default: false
      type: object
      required:
      - id
      - kind
      title: ActivityEventOut
    WatchlistDigestResponse:
      properties:
        digest:
          $ref: '#/components/schemas/WatchlistDigestSummary'
        entries:
          items:
            $ref: '#/components/schemas/WatchlistEntryDigest'
          type: array
          title: Entries
      type: object
      required:
      - digest
      - entries
      title: WatchlistDigestResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer