KOLens Workspace Billing API
The Workspace Billing API from KOLens — 5 operation(s) for workspace billing.
The Workspace Billing API from KOLens — 5 operation(s) for workspace billing.
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-workspace-billing-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 Workspace Billing API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: Workspace Billing
paths:
/api/workspaces/{slug}/billing/summary:
get:
tags:
- Workspace Billing
summary: Billing Summary
description: 'Current balance + last 5 purchases + month-to-date consumption.
Any workspace member can read this — billing transparency for the
team is by design, not an admin-only view. Top-up actions ARE
admin-gated (in the Next.js layer, before reaching Stripe).'
operationId: billing_summary_api_workspaces__slug__billing_summary_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/BillingSummaryOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/billing/history:
get:
tags:
- Workspace Billing
summary: Billing History
description: Full purchase history for the workspace (members only).
operationId: billing_history_api_workspaces__slug__billing_history_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/BillingHistoryOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/billing/credit-grant:
post:
tags:
- Workspace Billing
summary: Credit Grant
description: 'Webhook callback — credit a workspace from a confirmed Stripe payment.
Called by ``kolens-web/app/api/stripe/webhook/route.ts`` after
Stripe''s signature verifies. Idempotent on
``stripe_session_id`` (UNIQUE) — a duplicate delivery short-circuits
and returns ``credited=False`` with the current balance.
NOT api-key-gated — the Vercel webhook may not have a user session
when Stripe re-delivers, so we gate purely on ``X-Admin-Secret``.'
operationId: credit_grant_api_workspaces__slug__billing_credit_grant_post
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- name: X-Admin-Secret
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Admin-Secret
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreditGrantRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CreditGrantResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/billing/portal:
post:
tags:
- Workspace Billing
summary: Billing Portal
description: 'Confirm the caller can manage payment methods + return the
workspace''s Stripe customer id for the Vercel portal-session call.
Role gate: ``admin`` or ``billing`` only. Plain members → 403.
Workspaces that have never run a checkout don''t have a
``stripe_customer_id`` yet. We still return 200 with the field set
to null — the Vercel route surfaces a friendly "run a top-up first"
error instead of opening the portal.'
operationId: billing_portal_api_workspaces__slug__billing_portal_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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PortalCustomerOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{slug}/billing/portal/customer:
post:
tags:
- Workspace Billing
summary: Set Portal Customer
operationId: set_portal_customer_api_workspaces__slug__billing_portal_customer_post
parameters:
- name: slug
in: path
required: true
schema:
type: string
title: Slug
- name: X-Admin-Secret
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Admin-Secret
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SetPortalCustomerRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Set Portal Customer Api Workspaces Slug Billing Portal Customer Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
PortalCustomerOut:
properties:
workspace_id:
type: string
title: Workspace Id
slug:
type: string
title: Slug
stripe_customer_id:
anyOf:
- type: string
- type: 'null'
title: Stripe Customer Id
type: object
required:
- workspace_id
- slug
title: PortalCustomerOut
description: "Role-gated handshake the Vercel BFF uses to create a Stripe\nCustomer Portal session.\n\nThe Railway layer does NOT call Stripe itself — the Stripe SDK lives\nonly on Vercel (alongside the existing checkout + webhook flows).\nRailway's job here is purely:\n 1. Verify the caller's role (admin / billing — members are 403'd).\n 2. Return the workspace's persisted ``stripe_customer_id`` so the\n Vercel route can pass it into ``stripe.billingPortal.sessions\n .create``.\n\nIf no customer has been minted yet (workspace never ran a checkout),\n``stripe_customer_id`` is null. The Vercel route surfaces a clean\n\"Run a top-up first\" error instead of opening the portal."
SetPortalCustomerRequest:
properties:
stripe_customer_id:
type: string
maxLength: 64
minLength: 4
title: Stripe Customer Id
type: object
required:
- stripe_customer_id
title: SetPortalCustomerRequest
description: 'Admin-secret-gated callback. Stamps ``workspaces.stripe_customer_id``
after Vercel creates a customer via the first checkout. Idempotent —
re-setting to the same id is a no-op; changing to a different id
overwrites + audits the change.'
CreditGrantResponse:
properties:
credited:
type: boolean
title: Credited
workspace_id:
type: string
title: Workspace Id
balance:
type: number
title: Balance
purchase_id:
anyOf:
- type: string
- type: 'null'
title: Purchase Id
type: object
required:
- credited
- workspace_id
- balance
title: CreditGrantResponse
description: 'Return shape for the webhook callback.
``credited`` is False when the request was deduplicated (replayed
webhook with the same ``stripe_session_id``); in that case
``balance`` reflects the existing post-credit balance, so the
webhook can log "already processed" without re-crediting.'
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
PurchaseOut:
properties:
id:
type: string
title: Id
workspace_id:
type: string
title: Workspace Id
user_id:
anyOf:
- type: string
- type: 'null'
title: User Id
stripe_session_id:
type: string
title: Stripe Session Id
credits_purchased:
type: number
title: Credits Purchased
amount_cents:
type: integer
title: Amount Cents
status:
type: string
title: Status
receipt_url:
anyOf:
- type: string
- type: 'null'
title: Receipt Url
created_at:
type: string
format: date-time
title: Created At
type: object
required:
- id
- workspace_id
- stripe_session_id
- credits_purchased
- amount_cents
- status
- created_at
title: PurchaseOut
BillingSummaryOut:
properties:
workspace_id:
type: string
title: Workspace Id
slug:
type: string
title: Slug
balance:
type: number
title: Balance
monthly_consumed:
type: number
title: Monthly Consumed
recent_purchases:
items:
$ref: '#/components/schemas/PurchaseOut'
type: array
title: Recent Purchases
type: object
required:
- workspace_id
- slug
- balance
- monthly_consumed
title: BillingSummaryOut
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
CreditGrantRequest:
properties:
stripe_session_id:
type: string
maxLength: 128
minLength: 4
title: Stripe Session Id
credits:
type: number
exclusiveMinimum: 0.0
title: Credits
amount_cents:
type: integer
minimum: 0.0
title: Amount Cents
user_id:
anyOf:
- type: string
maxLength: 64
- type: 'null'
title: User Id
receipt_url:
anyOf:
- type: string
maxLength: 2048
- type: 'null'
title: Receipt Url
type: object
required:
- stripe_session_id
- credits
- amount_cents
title: CreditGrantRequest
BillingHistoryOut:
properties:
workspace_id:
type: string
title: Workspace Id
slug:
type: string
title: Slug
purchases:
items:
$ref: '#/components/schemas/PurchaseOut'
type: array
title: Purchases
type: object
required:
- workspace_id
- slug
title: BillingHistoryOut
securitySchemes:
HTTPBearer:
type: http
scheme: bearer