KOLens KOL Lists API
The KOL Lists API from KOLens — 7 operation(s) for kol lists.
The KOL Lists API from KOLens — 7 operation(s) for kol lists.
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-kol-lists-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 KOL Lists API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: KOL Lists
paths:
/api/lists:
post:
tags:
- KOL Lists
summary: Create List
description: 'Create a new named KOL library. When called with an active
workspace header, the list is stamped with that workspace_id so
every teammate can read/write it (EPIC #114 Phase 3).'
operationId: create_list_api_lists_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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ListOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- KOL Lists
summary: Get Lists
description: 'Return KOL lists owned by the calling user (or visible to the
caller''s active workspace), each with a compact decision ``rollup``.
With ``X-Kolens-User-Id`` (the normal web-app path), filter to lists
whose api_key resolves to that user via APIKey.user_id. Without it
(CLI / cowork plugin), fall back to per-api-key match. When an
active workspace is supplied, lists owned by the workspace are
also visible (EPIC #114 Phase 3).
GitHub #376 — every list carries a ``rollup``
``{member_count, n_shortlisted, n_untriaged, n_passed, n_red_flag}``
so the portfolio/index view can render "Skincare Q3 · 40 KOL · 8
shortlisted · 12 untriaged · 6 red-flag" without a per-list call.'
operationId: get_lists_api_lists_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:
type: array
items:
$ref: '#/components/schemas/ListOut'
title: Response Get Lists Api Lists Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/lists/{list_id}:
get:
tags:
- KOL Lists
summary: Get List
operationId: get_list_api_lists__list_id__get
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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/ListOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- KOL Lists
summary: Update List
description: 'Update mutable list-level settings.
Issue #391 — currently the only mutable field is
``enable_daily_monitoring``, the daily-snapshot opt-out flag. The
list-detail UI''s toggle calls this endpoint when the operator flips
the switch. Partial updates only: keys absent from the body are
left untouched on the persisted row.'
operationId: update_list_api_lists__list_id__patch
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ListOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- KOL Lists
summary: Delete List
operationId: delete_list_api_lists__list_id__delete
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/lists/{list_id}/members:
post:
tags:
- KOL Lists
summary: Add Members
description: 'Add KOLs to the list by username.
Silently skips usernames not found in the DB or already in the list.
Returns counts of added / skipped / not_found.'
operationId: add_members_api_lists__list_id__members_post
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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/api__schemas__lists__AddMembersRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Add Members Api Lists List Id Members Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- KOL Lists
summary: Get Members
description: 'Return the list as a single decision surface (GitHub #376).
ONE call yields everything the decision UI needs: per-member identity,
core stats, a 0-100 fit score + red/positive flags, growth trend,
tier + price range, contact completeness, the list-local
``triage_state``, and the CRM-derived ``outreach`` block (null when
the member has no conversation). ``entries`` is sorted by
``fit.score`` descending — the strongest candidate first — and a
top-level ``rollup`` summarises the batch.
The active workspace is resolved so the CRM outreach join + the
cached brand-fit recommendation score can be included. If resolution
fails the surface still returns — it just omits the workspace-scoped
fields rather than collapsing the whole view.'
operationId: get_members_api_lists__list_id__members_get
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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/MemberListOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/lists/{list_id}/enrich-contacts:
post:
tags:
- KOL Lists
summary: Enrich List Contacts
description: 'Find + verify a deliverable email for each member of the list.
Pay-for-result per member (workspace-first billing). Returns per-member
outcomes plus a rollup; ``stopped_insufficient_credits`` is True when
the loop halted because the next hit couldn''t be paid for.'
operationId: enrich_list_contacts_api_lists__list_id__enrich_contacts_post
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchEnrichRequest'
default:
only_missing: true
limit: 50
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Enrich List Contacts Api Lists List Id Enrich Contacts Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/lists/{list_id}/members/{username}:
patch:
tags:
- KOL Lists
summary: Update Member
description: 'Update the list-local triage state, tags, or notes for a member.
GitHub #376 — ``triage_state`` (``untriaged`` | ``shortlisted`` |
``passed``) is the operator''s per-list evaluation verdict. Outreach
funnel status is NOT settable here: it lives in the CRM
(``DBKolConversation``) and the decision surface reads it from there.'
operationId: update_member_api_lists__list_id__members__username__patch
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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/MemberUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Update Member Api Lists List Id Members Username Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- KOL Lists
summary: Remove Member
operationId: remove_member_api_lists__list_id__members__username__delete
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/lists/{list_id}/refresh:
post:
tags:
- KOL Lists
summary: Refresh Snapshots
description: 'Capture a new metric snapshot for every member in the list.
Call this periodically (e.g. weekly) to build trend data.
Returns the count of snapshots taken.'
operationId: refresh_snapshots_api_lists__list_id__refresh_post
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List 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:
type: object
title: Response Refresh Snapshots Api Lists List Id Refresh Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/lists/{list_id}/assign-export:
post:
tags:
- KOL Lists
summary: Assign Export
description: 'Slice this list across operators and return a single .xlsx with one
sheet per operator + a Summary tab. No state is mutated.'
operationId: assign_export_api_lists__list_id__assign_export_post
security:
- HTTPBearer: []
parameters:
- name: list_id
in: path
required: true
schema:
type: string
title: List Id
- 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/AssignExportRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ListUpdate:
properties:
enable_daily_monitoring:
anyOf:
- type: boolean
- type: 'null'
title: Enable Daily Monitoring
type: object
title: ListUpdate
description: 'PATCH shape for ``PATCH /api/lists/{id}``.
Issue #391 — the only mutable field on a list (so far) is
``enable_daily_monitoring``, the daily-snapshot opt-out toggle the
list-detail UI exposes in its header. All fields optional so partial
updates work; the route only applies the keys the caller sent.
Adding name/description here later is a non-breaking change.'
AssignFilters:
properties:
country:
anyOf:
- type: string
- type: 'null'
title: Country
min_followers:
anyOf:
- type: integer
- type: 'null'
title: Min Followers
max_followers:
anyOf:
- type: integer
- type: 'null'
title: Max Followers
require_email:
type: boolean
title: Require Email
default: false
tier_in:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Tier In
triage_state_in:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Triage State In
type: object
title: AssignFilters
description: Subset of filters available when carving up a list for assignment.
MemberUpdate:
properties:
triage_state:
anyOf:
- type: string
- type: 'null'
title: Triage State
tags:
anyOf:
- type: string
- type: 'null'
title: Tags
notes:
anyOf:
- type: string
- type: 'null'
title: Notes
type: object
title: MemberUpdate
description: 'PATCH shape for ``PATCH /api/lists/{id}/members/{username}``.
``triage_state`` is the list-local decision verdict — one of
``untriaged`` | ``shortlisted`` | ``passed``. Outreach funnel status
is NOT settable here any more: it lives in the CRM
(``DBKolConversation``). All fields optional so the UI can flip just
the triage state without re-sending tags/notes.'
MemberDecisionOut:
properties:
username:
type: string
title: Username
added_at:
anyOf:
- type: string
- type: 'null'
title: Added At
identity:
$ref: '#/components/schemas/MemberIdentityOut'
stats:
$ref: '#/components/schemas/MemberStatsOut'
fit:
$ref: '#/components/schemas/FitOut'
trend:
$ref: '#/components/schemas/MemberTrendOut'
pricing:
$ref: '#/components/schemas/MemberPricingOut'
contact:
$ref: '#/components/schemas/MemberContactOut'
triage_state:
type: string
title: Triage State
pursuing:
type: boolean
title: Pursuing
default: false
outreach:
anyOf:
- $ref: '#/components/schemas/MemberOutreachOut'
- type: 'null'
tags:
anyOf:
- type: string
- type: 'null'
title: Tags
notes:
anyOf:
- type: string
- type: 'null'
title: Notes
type: object
required:
- username
- identity
- stats
- fit
- trend
- pricing
- contact
- triage_state
title: MemberDecisionOut
description: One list member, fully decision-oriented — no per-row follow-up call.
MemberListOut:
properties:
list_id:
type: string
title: List Id
list_name:
type: string
title: List Name
rollup:
$ref: '#/components/schemas/ListDecisionRollup'
entries:
items:
$ref: '#/components/schemas/MemberDecisionOut'
type: array
title: Entries
type: object
required:
- list_id
- list_name
- rollup
- entries
title: MemberListOut
description: Response for ``GET /api/lists/{id}/members`` — the decision surface.
AssignExportRequest:
properties:
assignees:
items:
type: string
type: array
title: Assignees
strategy:
type: string
title: Strategy
default: round_robin
filters:
anyOf:
- $ref: '#/components/schemas/AssignFilters'
- type: 'null'
type: object
required:
- assignees
title: AssignExportRequest
ListIndexRollup:
properties:
member_count:
type: integer
title: Member Count
default: 0
n_shortlisted:
type: integer
title: N Shortlisted
default: 0
n_untriaged:
type: integer
title: N Untriaged
default: 0
n_passed:
type: integer
title: N Passed
default: 0
n_red_flag:
type: integer
title: N Red Flag
default: 0
type: object
title: ListIndexRollup
description: 'Compact decision rollup carried by each list in ``GET /api/lists``
so the portfolio view can show "Skincare Q3 · 40 KOL · 8 shortlisted
· 12 untriaged · 6 red-flag" without a per-list detail call.'
MemberOutreachOut:
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
type: object
required:
- conversation_id
- status
title: MemberOutreachOut
description: 'CRM-derived outreach status. Null on a member with no
``DBKolConversation``. The list never stores this — it is the CRM''s.'
ListCreate:
properties:
name:
type: string
title: Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
type: object
required:
- name
title: ListCreate
FitOut:
properties:
score:
type: integer
title: Score
flags:
items:
$ref: '#/components/schemas/FitFlagOut'
type: array
title: Flags
default: []
type: object
required:
- score
title: FitOut
MemberPricingOut:
properties:
tier:
anyOf:
- type: string
- type: 'null'
title: Tier
estimated_price_min:
anyOf:
- type: number
- type: 'null'
title: Estimated Price Min
estimated_price_max:
anyOf:
- type: number
- type: 'null'
title: Estimated Price Max
type: object
title: MemberPricingOut
ListOut:
properties:
id:
type: string
title: Id
name:
type: string
title: Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
member_count:
type: integer
title: Member Count
created_at:
type: string
title: Created At
updated_at:
type: string
title: Updated At
enable_daily_monitoring:
type: boolean
title: Enable Daily Monitoring
default: true
rollup:
$ref: '#/components/schemas/ListIndexRollup'
type: object
required:
- id
- name
- description
- member_count
- created_at
- updated_at
title: ListOut
MemberIdentityOut:
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
platform:
anyOf:
- type: string
- type: 'null'
title: Platform
type: object
required:
- username
title: MemberIdentityOut
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
api__schemas__lists__AddMembersRequest:
properties:
usernames:
items:
type: string
type: array
title: Usernames
type: object
required:
- usernames
title: AddMembersRequest
MemberTrendOut:
properties:
follower_delta:
anyOf:
- type: integer
- type: 'null'
title: Follower Delta
follower_delta_pct:
anyOf:
- type: number
- type: 'null'
title: Follower Delta Pct
er_delta:
anyOf:
- type: number
- type: 'null'
title: Er Delta
trend_label:
anyOf:
- type: string
- type: 'null'
title: Trend Label
type: object
title: MemberTrendOut
description: Growth trend from the two most-recent ``KOLSnapshot`` rows.
ListDecisionRollup:
properties:
total_members:
type: integer
title: Total Members
default: 0
n_untriaged:
type: integer
title: N Untriaged
default: 0
n_shortlisted:
type: integer
title: N Shortlisted
default: 0
n_passed:
type: integer
title: N Passed
default: 0
n_pursuing:
type: integer
title: N Pursuing
default: 0
n_red_flag:
type: integer
title: N Red Flag
default: 0
n_missing_contact:
type: integer
title: N Missing Contact
default: 0
total_estimated_price_min:
type: number
title: Total Estimated Price Min
default: 0.0
total_estimated_price_max:
type: number
title: Total Estimated Price Max
default: 0.0
type: object
title: ListDecisionRollup
description: 'Top-level decision rollup — answers "what does this batch look
like?" so the detail UI renders a header without scanning rows.'
MemberStatsOut:
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
authenticity_score:
anyOf:
- type: integer
- type: 'null'
title: Authenticity Score
recommendation_score:
anyOf:
- type: integer
- type: 'null'
title: Recommendation Score
type: object
title: MemberStatsOut
BatchEnrichRequest:
properties:
only_missing:
type: boolean
title: Only Missing
description: Skip members that already have a verified email.
default: true
limit:
type: integer
maximum: 100.0
minimum: 1.0
title: Limit
description: Max members to process this call.
default: 50
type: object
title: BatchEnrichRequest
FitFlagOut:
properties:
code:
type: string
title: Code
severity:
type: string
title: Severity
detail:
type: string
title: Detail
type: object
required:
- code
- severity
- detail
title: FitFlagOut
description: One decision signal on a member's row.
MemberContactOut:
properties:
email:
anyOf:
- type: string
- type: 'null'
title: Email
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
website:
anyOf:
- type: string
- type: 'null'
title: Website
instagram:
anyOf:
- type: string
- type: 'null'
title: Instagram
youtube:
anyOf:
- type: string
- type: 'null'
title: Youtube
linktree_url:
anyOf:
- type: string
- type: 'null'
title: Linktree Url
has_email:
type: boolean
title: Has Email
default: false
has_website:
type: boolean
title: Has Website
default: false
is_complete:
type: boolean
title: Is Complete
default: false
type: object
title: MemberContactOut
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer