KOLens Campaigns API
The Campaigns API from KOLens — 6 operation(s) for campaigns.
The Campaigns API from KOLens — 6 operation(s) for campaigns.
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-campaigns-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 Campaigns API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: Campaigns
paths:
/api/campaigns:
post:
tags:
- Campaigns
summary: Create Campaign
operationId: create_campaign_api_campaigns_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/CampaignIn'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Create Campaign Api Campaigns Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Campaigns
summary: List Campaigns
description: 'Every campaign in the workspace, each with its full summary.
The summary is included rather than a bare list: the list view''s
whole job is to show spend against budget, and fetching that per
row would be N requests to render one page.'
operationId: list_campaigns_api_campaigns_get
security:
- HTTPBearer: []
parameters:
- name: status
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Status
- 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: object
title: Response List Campaigns Api Campaigns Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/campaigns/{campaign_id}:
get:
tags:
- Campaigns
summary: Get Campaign
operationId: get_campaign_api_campaigns__campaign_id__get
security:
- HTTPBearer: []
parameters:
- name: campaign_id
in: path
required: true
schema:
type: string
title: Campaign 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:
type: object
title: Response Get Campaign Api Campaigns Campaign Id Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Campaigns
summary: Update Campaign
operationId: update_campaign_api_campaigns__campaign_id__patch
security:
- HTTPBearer: []
parameters:
- name: campaign_id
in: path
required: true
schema:
type: string
title: Campaign 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/CampaignPatch'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Update Campaign Api Campaigns Campaign Id Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Campaigns
summary: Delete Campaign
description: 'Delete a campaign and its placements.
Attached videos survive. Tracking a video and having paid for it are
different facts, and losing the tracking because the bookkeeping was
tidied would be genuine data loss.
The detach is done here rather than left to the column''s
``ON DELETE SET NULL``. That clause describes the model, but
``placement_id`` reaches the deployed table through
``ALTER TABLE ... ADD COLUMN`` in ``run_alter_migrations``, which
adds no constraint — so in production there is no foreign key to
act on and the videos would be left pointing at placements that no
longer exist. Doing it explicitly is the only version that is true
on both the model and the live database.'
operationId: delete_campaign_api_campaigns__campaign_id__delete
security:
- HTTPBearer: []
parameters:
- name: campaign_id
in: path
required: true
schema:
type: string
title: Campaign 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/campaigns/{campaign_id}/placements:
post:
tags:
- Campaigns
summary: Create Placement
description: 'Record a creator''s paid slot in this campaign.
A placement may be created with no amount and no video: a deal
agreed but neither paid nor published is a real state, and the
operator wants it on the board rather than in their head.'
operationId: create_placement_api_campaigns__campaign_id__placements_post
security:
- HTTPBearer: []
parameters:
- name: campaign_id
in: path
required: true
schema:
type: string
title: Campaign 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/PlacementIn'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Create Placement Api Campaigns Campaign Id Placements Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/campaigns/{campaign_id}/placements/{placement_id}:
patch:
tags:
- Campaigns
summary: Update Placement
operationId: update_placement_api_campaigns__campaign_id__placements__placement_id__patch
security:
- HTTPBearer: []
parameters:
- name: campaign_id
in: path
required: true
schema:
type: string
title: Campaign Id
- name: placement_id
in: path
required: true
schema:
type: string
title: Placement 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/PlacementIn'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Update Placement Api Campaigns Campaign Id Placements Placement Id Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Campaigns
summary: Delete Placement
operationId: delete_placement_api_campaigns__campaign_id__placements__placement_id__delete
security:
- HTTPBearer: []
parameters:
- name: campaign_id
in: path
required: true
schema:
type: string
title: Campaign Id
- name: placement_id
in: path
required: true
schema:
type: string
title: Placement 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/campaigns/{campaign_id}/placements/{placement_id}/videos:
post:
tags:
- Campaigns
summary: Attach Video
description: 'Attach one of the caller''s tracked videos to this placement.
This is where two visibility rules meet. A tracked video is shared
with a workspace only when its owner opts in; a campaign is the
team''s by construction. Attaching therefore stamps the video with
the campaign''s workspace — otherwise a teammate would see the spend
but not the video it bought, and the page would be arithmetic they
could not check.
``shared_with_workspace`` in the response reports whether that just
happened, so the client can warn BEFORE the click rather than
apologise after.'
operationId: attach_video_api_campaigns__campaign_id__placements__placement_id__videos_post
security:
- HTTPBearer: []
parameters:
- name: campaign_id
in: path
required: true
schema:
type: string
title: Campaign Id
- name: placement_id
in: path
required: true
schema:
type: string
title: Placement 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/AttachVideoIn'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Attach Video Api Campaigns Campaign Id Placements Placement Id Videos Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/campaigns/{campaign_id}/placements/{placement_id}/videos/{video_id}:
delete:
tags:
- Campaigns
summary: Detach Video
description: 'Detach a video from its placement.
Tracking continues and the workspace stamp stays: detaching says
"this video was not what we bought", not "un-share it". Reversing
the share is a separate decision with its own consequences.'
operationId: detach_video_api_campaigns__campaign_id__placements__placement_id__videos__video_id__delete
security:
- HTTPBearer: []
parameters:
- name: campaign_id
in: path
required: true
schema:
type: string
title: Campaign Id
- name: placement_id
in: path
required: true
schema:
type: string
title: Placement Id
- name: video_id
in: path
required: true
schema:
type: string
title: Video 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:
type: object
title: Response Detach Video Api Campaigns Campaign Id Placements Placement Id Videos Video Id Delete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
AttachVideoIn:
properties:
video_id:
type: string
maxLength: 50
minLength: 1
title: Video Id
type: object
required:
- video_id
title: AttachVideoIn
CampaignPatch:
properties:
name:
anyOf:
- type: string
maxLength: 200
minLength: 1
- type: 'null'
title: Name
product:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Product
budget_amount:
anyOf:
- type: number
minimum: 0.0
- type: 'null'
title: Budget Amount
currency:
anyOf:
- type: string
maxLength: 3
minLength: 3
- type: 'null'
title: Currency
target_regions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Target Regions
starts_on:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Starts On
ends_on:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ends On
status:
anyOf:
- type: string
- type: 'null'
title: Status
note:
anyOf:
- type: string
maxLength: 4000
- type: 'null'
title: Note
type: object
title: CampaignPatch
CampaignIn:
properties:
name:
type: string
maxLength: 200
minLength: 1
title: Name
product:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Product
budget_amount:
anyOf:
- type: number
minimum: 0.0
- type: 'null'
title: Budget Amount
currency:
type: string
maxLength: 3
minLength: 3
title: Currency
default: USD
target_regions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Target Regions
starts_on:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Starts On
ends_on:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ends On
status:
type: string
title: Status
default: active
note:
anyOf:
- type: string
maxLength: 4000
- type: 'null'
title: Note
type: object
required:
- name
title: CampaignIn
PlacementIn:
properties:
kol_username:
type: string
maxLength: 120
minLength: 1
title: Kol Username
kol_platform:
type: string
maxLength: 20
title: Kol Platform
default: tiktok
amount:
anyOf:
- type: number
minimum: 0.0
- type: 'null'
title: Amount
currency:
anyOf:
- type: string
maxLength: 3
minLength: 3
- type: 'null'
title: Currency
fx_rate_to_campaign:
anyOf:
- type: number
exclusiveMinimum: 0.0
- type: 'null'
title: Fx Rate To Campaign
description: Rate to the campaign's currency, frozen at entry. Required only when the placement currency differs.
status:
type: string
title: Status
default: planned
paid_on:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Paid On
note:
anyOf:
- type: string
maxLength: 2000
- type: 'null'
title: Note
type: object
required:
- kol_username
title: PlacementIn
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
securitySchemes:
HTTPBearer:
type: http
scheme: bearer