KOLens Workspace Billing API

The Workspace Billing API from KOLens — 5 operation(s) for workspace billing.

GitHub OpenAPI

Operations 5

GET /api/workspaces/{slug}/billing/summary Billing Summary #
GET /api/workspaces/{slug}/billing/history Billing History #
POST /api/workspaces/{slug}/billing/credit-grant Credit Grant #
POST /api/workspaces/{slug}/billing/portal Billing Portal #
POST /api/workspaces/{slug}/billing/portal/customer Set Portal Customer #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/kolens-ai:kolens-ai-workspace-billing-api"
All apis
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.

Get an API 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 Specification

kolens-ai-workspace-billing-api-openapi.yml Raw ↑
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