KOLens Workspaces API
The Workspaces API from KOLens — 11 operation(s) for workspaces.
The Workspaces API from KOLens — 11 operation(s) for workspaces.
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-workspaces-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 Workspaces API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: Workspaces
paths:
/api/workspaces:
post:
tags:
- Workspaces
summary: Create
operationId: create_api_workspaces_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/CreateWorkspaceRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Workspaces
summary: List Mine
description: 'List the caller''s workspaces.
Phase 2 wiring (EPIC #114): on first call this lazily creates the
user''s "Personal" workspace via ``ensure_personal_workspace``. We
chose lazy-on-list rather than a global request middleware because:
1. It only runs for endpoints that already resolve a user_id, so
OAuth flows and health probes are untouched.
2. The frontend always hits ``/api/workspaces`` to render the
switcher on dashboard load, so the latency cost is amortised.
3. ``ensure_personal_workspace`` is idempotent and race-safe (it
checks for an existing Personal workspace by name+owner before
inserting), so multiple concurrent requests converge to one row.'
operationId: list_mine_api_workspaces_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-user-email
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Email
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceListOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}:
get:
tags:
- Workspaces
summary: Detail
operationId: detail_api_workspaces__slug__get
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- 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/WorkspaceDetailOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/invitations:
post:
tags:
- Workspaces
summary: Invite
operationId: invite_api_workspaces__slug__invitations_post
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- 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/InviteRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InvitationOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/invitations/{invitation_id}:
delete:
tags:
- Workspaces
summary: Revoke
operationId: revoke_api_workspaces__slug__invitations__invitation_id__delete
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- name: invitation_id
in: path
required: true
schema:
type: string
title: Invitation Id
- 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/workspaces/invitations/accept:
post:
tags:
- Workspaces
summary: Accept
description: 'Redeem an invitation token. The caller''s user_id (from the
Vercel proxy) becomes a member of the invited workspace.'
operationId: accept_api_workspaces_invitations_accept_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/AcceptInvitationRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptInvitationOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/members/{member_user_id}:
patch:
tags:
- Workspaces
summary: Update Member
operationId: update_member_api_workspaces__slug__members__member_user_id__patch
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- name: member_user_id
in: path
required: true
schema:
type: string
title: Member User 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/ChangeRoleRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MemberOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Workspaces
summary: Remove
operationId: remove_api_workspaces__slug__members__member_user_id__delete
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- name: member_user_id
in: path
required: true
schema:
type: string
title: Member User Id
- 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/workspaces/{slug}/members/activity:
get:
tags:
- Workspaces
summary: Members Activity
operationId: members_activity_api_workspaces__slug__members_activity_get
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- name: since
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 timestamp. Counters cover events at or after this point in time. Omit (or pass an empty string) for all-time.
title: Since
description: ISO 8601 timestamp. Counters cover events at or after this point in time. Omit (or pass an empty string) for all-time.
- 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/MemberActivityListOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/auto-join:
get:
tags:
- Workspaces
summary: Get Auto Join
operationId: get_auto_join_api_workspaces__slug__auto_join_get
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- 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/AutoJoinDomainsOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Workspaces
summary: Patch Auto Join
operationId: patch_auto_join_api_workspaces__slug__auto_join_patch
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- 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/UpdateAutoJoinDomainsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AutoJoinDomainsOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/settings:
get:
tags:
- Workspaces
summary: Get Settings
operationId: get_settings_api_workspaces__slug__settings_get
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- 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/WorkspaceSettingsOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Workspaces
summary: Put Settings
operationId: put_settings_api_workspaces__slug__settings_put
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- 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/UpdateWorkspaceSettingsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceSettingsOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/data-sync/preview:
get:
tags:
- Workspaces
summary: Preview Data Sync
description: 'How much of the caller''s own data would become team data.
Read-only. The UI shows this count next to the button so nobody
publishes a month of research to find out how much it was.'
operationId: preview_data_sync_api_workspaces__slug__data_sync_preview_get
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- 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 Preview Data Sync Api Workspaces Slug Data Sync Preview Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/data-sync:
post:
tags:
- Workspaces
summary: Run Data Sync
description: 'Share the caller''s own existing data with this workspace.
Any member may do this FOR THEMSELVES — that is the whole point, and
it is why there is no admin role check: an admin pressing this on
someone else''s behalf is exactly what the opt-in exists to prevent.
``require_workspace_membership`` without a role therefore reads as
intended, not as a missing gate.
Data created from here on is stamped at creation, so this is a
one-time catch-up for what already existed. Idempotent — running it
again moves nothing.'
operationId: run_data_sync_api_workspaces__slug__data_sync_post
security:
- HTTPBearer: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- name: confirm
in: query
required: false
schema:
type: boolean
description: Must be true — this publishes data
default: false
title: Confirm
description: Must be true — this publishes data
- 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 Run Data Sync Api Workspaces Slug Data Sync Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
InvitationOut:
properties:
id:
type: string
title: Id
workspace_id:
type: string
title: Workspace Id
email:
type: string
title: Email
role:
type: string
enum:
- admin
- billing
- member
title: Role
token:
type: string
title: Token
expires_at:
type: string
format: date-time
title: Expires At
created_at:
type: string
format: date-time
title: Created At
type: object
required:
- id
- workspace_id
- email
- role
- token
- expires_at
- created_at
title: InvitationOut
AcceptInvitationRequest:
properties:
token:
type: string
maxLength: 128
minLength: 8
title: Token
type: object
required:
- token
title: AcceptInvitationRequest
InviteRequest:
properties:
email:
type: string
maxLength: 255
minLength: 3
title: Email
role:
type: string
enum:
- admin
- billing
- member
title: Role
default: member
type: object
required:
- email
title: InviteRequest
MemberActivityListOut:
properties:
workspace_id:
type: string
title: Workspace Id
slug:
type: string
title: Slug
since:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Since
rows:
items:
$ref: '#/components/schemas/MemberActivityOut'
type: array
title: Rows
type: object
required:
- workspace_id
- slug
- rows
title: MemberActivityListOut
MemberActivityOut:
properties:
user_id:
type: string
title: User Id
role:
type: string
enum:
- admin
- billing
- member
title: Role
joined_at:
type: string
format: date-time
title: Joined At
last_active_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Active At
search_count:
type: integer
title: Search Count
default: 0
watch_count:
type: integer
title: Watch Count
default: 0
scrape_count:
type: integer
title: Scrape Count
default: 0
audience_refresh_count:
type: integer
title: Audience Refresh Count
default: 0
credits_consumed:
type: number
title: Credits Consumed
default: 0.0
type: object
required:
- user_id
- role
- joined_at
title: MemberActivityOut
description: 'One row of the workspace''s "member activity" table.
All counters are integers except ``credits_consumed`` (float —
``search_jobs.credits_charged`` is FLOAT in the schema). The route
layer scopes time-bounded counters to a caller-supplied ``since``
window; ``watch_count`` is always the current cumulative count.'
UpdateWorkspaceSettingsRequest:
properties:
brand_voice_text:
anyOf:
- type: string
maxLength: 20000
- type: 'null'
title: Brand Voice Text
product_category:
anyOf:
- type: string
maxLength: 100
- type: 'null'
title: Product Category
target_audience_text:
anyOf:
- type: string
maxLength: 4000
- type: 'null'
title: Target Audience Text
target_geographies:
anyOf:
- items:
type: string
type: array
maxItems: 50
- type: 'null'
title: Target Geographies
exclusions_text:
anyOf:
- type: string
maxLength: 4000
- type: 'null'
title: Exclusions Text
sender_name:
anyOf:
- type: string
maxLength: 120
- type: 'null'
title: Sender Name
sender_title:
anyOf:
- type: string
maxLength: 120
- type: 'null'
title: Sender Title
sender_brand_name:
anyOf:
- type: string
maxLength: 120
- type: 'null'
title: Sender Brand Name
email_signature:
anyOf:
- type: string
maxLength: 2000
- type: 'null'
title: Email Signature
type: object
title: UpdateWorkspaceSettingsRequest
MemberOut:
properties:
id:
type: string
title: Id
user_id:
type: string
title: User Id
role:
type: string
enum:
- admin
- billing
- member
title: Role
invited_by_user_id:
anyOf:
- type: string
- type: 'null'
title: Invited By User Id
joined_at:
type: string
format: date-time
title: Joined At
type: object
required:
- id
- user_id
- role
- joined_at
title: MemberOut
WorkspaceOut:
properties:
id:
type: string
title: Id
name:
type: string
title: Name
slug:
type: string
title: Slug
owner_user_id:
type: string
title: Owner User Id
plan:
type: string
title: Plan
role:
anyOf:
- type: string
enum:
- admin
- billing
- member
- type: 'null'
title: Role
member_count:
anyOf:
- type: integer
- type: 'null'
title: Member Count
is_personal:
anyOf:
- type: boolean
- type: 'null'
title: Is Personal
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- name
- slug
- owner_user_id
- plan
- created_at
- updated_at
title: WorkspaceOut
WorkspaceListOut:
properties:
workspaces:
items:
$ref: '#/components/schemas/WorkspaceOut'
type: array
title: Workspaces
type: object
required:
- workspaces
title: WorkspaceListOut
CreateWorkspaceRequest:
properties:
name:
type: string
maxLength: 200
minLength: 1
title: Name
slug:
anyOf:
- type: string
maxLength: 80
- type: 'null'
title: Slug
plan:
anyOf:
- type: string
maxLength: 20
- type: 'null'
title: Plan
default: free
type: object
required:
- name
title: CreateWorkspaceRequest
AutoJoinDomainsOut:
properties:
workspace_id:
type: string
title: Workspace Id
slug:
type: string
title: Slug
domains:
items:
type: string
type: array
title: Domains
type: object
required:
- workspace_id
- slug
- domains
title: AutoJoinDomainsOut
WorkspaceDetailOut:
properties:
id:
type: string
title: Id
name:
type: string
title: Name
slug:
type: string
title: Slug
owner_user_id:
type: string
title: Owner User Id
plan:
type: string
title: Plan
role:
anyOf:
- type: string
enum:
- admin
- billing
- member
- type: 'null'
title: Role
member_count:
anyOf:
- type: integer
- type: 'null'
title: Member Count
is_personal:
anyOf:
- type: boolean
- type: 'null'
title: Is Personal
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
members:
items:
$ref: '#/components/schemas/MemberOut'
type: array
title: Members
invitations:
anyOf:
- items:
$ref: '#/components/schemas/InvitationOut'
type: array
- type: 'null'
title: Invitations
type: object
required:
- id
- name
- slug
- owner_user_id
- plan
- created_at
- updated_at
- members
title: WorkspaceDetailOut
UpdateAutoJoinDomainsRequest:
properties:
domains:
items:
type: string
type: array
maxItems: 50
title: Domains
type: object
title: UpdateAutoJoinDomainsRequest
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
AcceptInvitationOut:
properties:
workspace_id:
type: string
title: Workspace Id
workspace_slug:
type: string
title: Workspace Slug
role:
type: string
enum:
- admin
- billing
- member
title: Role
joined_at:
type: string
format: date-time
title: Joined At
type: object
required:
- workspace_id
- workspace_slug
- role
- joined_at
title: AcceptInvitationOut
ChangeRoleRequest:
properties:
role:
type: string
enum:
- admin
- billing
- member
title: Role
type: object
required:
- role
title: ChangeRoleRequest
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
WorkspaceSettingsOut:
properties:
id:
type: string
title: Id
slug:
type: string
title: Slug
brand_voice_text:
anyOf:
- type: string
- type: 'null'
title: Brand Voice Text
product_category:
anyOf:
- type: string
- type: 'null'
title: Product Category
target_audience_text:
anyOf:
- type: string
- type: 'null'
title: Target Audience Text
target_geographies:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Target Geographies
exclusions_text:
anyOf:
- type: string
- type: 'null'
title: Exclusions Text
sender_name:
anyOf:
- type: string
- type: 'null'
title: Sender Name
sender_title:
anyOf:
- type: string
- type: 'null'
title: Sender Title
sender_brand_name:
anyOf:
- type: string
- type: 'null'
title: Sender Brand Name
email_signature:
anyOf:
- type: string
- type: 'null'
title: Email Signature
ai_credits_used_today:
type: integer
title: Ai Credits Used Today
default: 0
ai_credits_day:
anyOf:
- type: string
- type: 'null'
title: Ai Credits Day
ai_daily_token_cap:
type: integer
title: Ai Daily Token Cap
default: 0
type: object
required:
- id
- slug
title: WorkspaceSettingsOut
description: 'Admin-visible settings on a workspace. Phase 2 ships
``brand_voice_text`` (the AI compose doc) and the daily-credits
counter so the settings UI can show usage / cap. Phase 3 (EPIC
#198) adds the four structured brand-profile fields used by the
KOL brand-fit scoring path.'
securitySchemes:
HTTPBearer:
type: http
scheme: bearer