KOLens Search Insights API
The Search Insights API from KOLens — 4 operation(s) for search insights.
The Search Insights API from KOLens — 4 operation(s) for search insights.
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-search-insights-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 Search Insights API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: Search Insights
paths:
/api/search-insights:
post:
tags:
- Search Insights
summary: Create Insight
operationId: create_insight_api_search_insights_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/CreateInsightRequest'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInsightResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/search-insights/{insight_id}:
get:
tags:
- Search Insights
summary: Get Insight
operationId: get_insight_api_search_insights__insight_id__get
security:
- HTTPBearer: []
parameters:
- name: insight_id
in: path
required: true
schema:
type: string
title: Insight 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/InsightDetail'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/search-insights/{insight_id}/export/notion:
post:
tags:
- Search Insights
summary: Export Insight To Notion
description: 'Push a ready insight report into a Notion database as a new
page. The caller supplies a Notion integration token + target
database id; nothing is persisted server-side.
Token is one-shot per request — never stored. Returns the created
Notion page id + URL on success.
Rate-limited to 5 calls / 60s per workspace (best-effort; keyed on
workspace_id once resolved, falling back to api_key + user_id
before workspace resolution).'
operationId: export_insight_to_notion_api_search_insights__insight_id__export_notion_post
security:
- HTTPBearer: []
parameters:
- name: insight_id
in: path
required: true
schema:
type: string
title: Insight 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/NotionExportRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/NotionExportResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/search-insights/{insight_id}/regenerate:
post:
tags:
- Search Insights
summary: Regenerate Insight
description: 'Kick off a fresh generation, overwriting the existing row.
EPIC #117 Phase 3 — Regenerate flips the existing insight back to
``pending`` and schedules a fresh generation against the same
(workspace_id, keyword, intent) tuple. When the background task
completes it overwrites ``report_json`` + bumps ``generated_at`` so
the row id stays stable and any pinned UI / link to the report
continues to work.
Section-scoped regenerate is still in the contract for forwards-
compat but not yet wired (Phase 4 polish). Membership gate is
strict 404 so we never leak the existence of an insight in a
different workspace.
Rate-limited to 5 calls / 60s per (workspace_id, insight_id). The
BFF can forward Retry-After to the UI.'
operationId: regenerate_insight_api_search_insights__insight_id__regenerate_post
security:
- HTTPBearer: []
parameters:
- name: insight_id
in: path
required: true
schema:
type: string
title: Insight 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/RegenerateRequest'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateInsightResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
NotionExportResponse:
properties:
notion_page_id:
type: string
title: Notion Page Id
url:
type: string
title: Url
type: object
required:
- notion_page_id
- url
title: NotionExportResponse
CreateInsightRequest:
properties:
keyword:
type: string
maxLength: 200
minLength: 1
title: Keyword
intent:
anyOf:
- type: string
- type: 'null'
title: Intent
description: 'Optional explicit intent. When omitted, the classifier decides. Valid values: kol_discovery, content_inspiration, competitive_research, trend_research, unclassified'
context:
anyOf:
- type: string
maxLength: 2000
- type: 'null'
title: Context
source_job_id:
anyOf:
- type: string
- type: 'null'
title: Source Job Id
type: object
required:
- keyword
title: CreateInsightRequest
CreateInsightResponse:
properties:
insight_id:
type: string
title: Insight Id
status:
type: string
title: Status
intent:
type: string
title: Intent
keyword:
type: string
title: Keyword
cached:
type: boolean
title: Cached
default: false
type: object
required:
- insight_id
- status
- intent
- keyword
title: CreateInsightResponse
InsightDetail:
properties:
id:
type: string
title: Id
workspace_id:
type: string
title: Workspace Id
keyword:
type: string
title: Keyword
intent:
type: string
title: Intent
status:
type: string
title: Status
schema_version:
type: string
title: Schema Version
default: '1.0'
report_json:
anyOf:
- type: object
- type: 'null'
title: Report Json
error_text:
anyOf:
- type: string
- type: 'null'
title: Error Text
llm_tokens_used:
type: integer
title: Llm Tokens Used
source_job_id:
anyOf:
- type: string
- type: 'null'
title: Source Job Id
generated_at:
type: string
title: Generated At
expires_at:
anyOf:
- type: string
- type: 'null'
title: Expires At
stale:
type: boolean
title: Stale
default: false
type: object
required:
- id
- workspace_id
- keyword
- intent
- status
- llm_tokens_used
- generated_at
title: InsightDetail
NotionExportRequest:
properties:
notion_token:
type: string
maxLength: 200
minLength: 10
title: Notion Token
database_id:
type: string
maxLength: 64
minLength: 10
title: Database Id
type: object
required:
- notion_token
- database_id
title: NotionExportRequest
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
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
RegenerateRequest:
properties:
section:
anyOf:
- type: string
- type: 'null'
title: Section
type: object
title: RegenerateRequest
securitySchemes:
HTTPBearer:
type: http
scheme: bearer