Skip to content
Knobs Docs

Billing

Billing is per workspace. These routes are workspace-scoped, require membership, and accept a session JWT or API key. Plan semantics (tiers, seats, pooled storage, quotas) are described in the admin billing guide.

Endpoints

Section titled “Endpoints”
Endpoint Description
GET /v1/workspaces/{wid}/billing The workspace’s billing account — plan, live seat count, storage use vs quota, entitlements
GET /v1/workspaces/{wid}/billing/subscription Alias of the billing account read
GET /v1/workspaces/{wid}/billing/usage Usage summary — plan, seats, storageBytes against storageQuotaBytes, entitlements
POST /v1/workspaces/{wid}/billing/checkout Begin an upgrade {"plan": "team" | "business"}
POST /v1/workspaces/{wid}/billing/portal Open the billing portal for an existing subscription

Read the billing account

Section titled “Read the billing account”
Terminal window
curl -H "Authorization: Bearer knak_..." \
  https://api.knobs.io/v1/workspaces/{wid}/billing
{
  "workspaceId": "w_5d81…",
  "plan": "free",
  "subscriptionStatus": "",
  "seatCount": 3,
  "storageBytes": 104857600,
  "storageQuotaBytes": 5368709120,
  "entitlements": { "storagePerSeatBytes": 5368709120, "webRunsPerMonth": 50 }
}

Seats are counted live from active memberships (invited or suspended members don’t consume a seat), and the storage quota is pooled — the per-seat allowance × seats, shared by the whole workspace.

Start an upgrade

Section titled “Start an upgrade”
Terminal window
curl -X POST https://api.knobs.io/v1/workspaces/{wid}/billing/checkout \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"plan": "team"}'

plan must be team or business — anything else (including free) returns 400 invalid_plan. The response is a checkout session {workspaceId, plan, checkoutUrl, stub, note}.

Section titled “Related”