Billing API

Retrieve billing information and perform subscription actions such as creating a checkout session, enabling bring-your-own-key (BYOK) mode, checking usage, and purchasing credit packs.

All billing endpoints require session authentication.

Get billing info

GET /api/billing

Returns the available plans, the authenticated user’s current plan, subscription status, BYOK status, and daily usage.

Response

{
  "plans": {
    "starter": {
      "name": "Starter",
      "price": 19,
      "dailyUnits": 600,
      "features": ["1 AI Agent", "2GB RAM", "Telegram", "Basic skills"]
    },
    "pro": {
      "name": "Pro",
      "price": 39,
      "dailyUnits": 1000,
      "features": ["1 AI Agent", "4GB RAM", "All channels", "All skills", "Priority support"]
    },
    "scale": {
      "name": "Scale",
      "price": 79,
      "dailyUnits": 2500,
      "features": ["3 AI Agents", "8GB RAM", "All channels", "All skills", "Analytics"]
    }
  },
  "currentPlan": "starter",
  "subscriptionStatus": "active",
  "byokEnabled": false,
  "usage": {
    "dailyUnits": 600,
    "used": 245,
    "remaining": 355
  }
}

Response fields

Field	Type	Description
`plans`	object	Map of available plans with pricing and features
`currentPlan`	string	User’s current plan (`free`, `starter`, `pro`, or `scale`)
`subscriptionStatus`	string	Stripe subscription status (`active`, `inactive`, etc.)
`byokEnabled`	boolean	Whether BYOK mode is active
`usage.dailyUnits`	number	Daily unit allowance for the current plan
`usage.used`	number	Units used today
`usage.remaining`	number	Units remaining today

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed to fetch billing info

Billing actions

POST /api/billing

Performs a billing action. The action field in the request body determines which operation is executed.

Create checkout session

Creates a Stripe checkout session for subscribing to a plan.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `create-checkout`
`plan`	string	Yes	Plan to subscribe to: `starter`, `pro`, or `scale`

Response

{
  "url": "https://checkout.stripe.com/c/pay/..."
}

Redirect the user to the returned url to complete payment.

Errors

Code	Description
400	Invalid plan

Enable BYOK

Enables bring-your-own-key mode with an external AI provider. When BYOK is active, AI requests are billed directly by the provider rather than consuming platform credits.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `enable-byok`
`apiKey`	string	Yes	Your API key for the external provider
`provider`	string	Yes	Provider name (for example, `openai`, `anthropic`)

Response

{
  "success": true,
  "message": "BYOK enabled with openai. You'll pay openai directly for AI usage."
}

Errors

Code	Description
400	API key and provider are required

Disable BYOK

Disables BYOK mode and reverts to platform credits.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `disable-byok`

Response

{
  "success": true,
  "message": "BYOK disabled. Using platform credits."
}

Get usage

Returns the current day’s unit consumption.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `get-usage`

Response

{
  "dailyUnits": 600,
  "used": 245,
  "remaining": 355,
  "resetsAt": "midnight UTC"
}

Buy credits

Purchases a credit pack.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `buy-credits`
`pack`	string	Yes	Pack size: `50`, `200`, or `500`

Response

{
  "success": true,
  "credits": 15,
  "price": "$15"
}

Pack size	Credits
`50`	5
`200`	15
`500`	30

Errors

Code	Description
400	Invalid pack

Common errors

These apply to all billing POST actions:

Code	Description
400	Invalid action
401	Unauthorized — no valid session
500	Internal error

Subscription deploy

POST /api/subscriptions/deploy

Records a subscription-to-plan mapping so the next agent deployment uses the correct resource tier. This endpoint is called by the Stripe webhook after a checkout completes.

This is a backend-only endpoint that requires bearer token (API key) authentication.

Request body

Field	Type	Required	Description
`tier`	string	Yes	Plan tier. One of: `solo`, `collective`, `label`, `network`, `underground`, `starter`, `pro`, `scale`, `enterprise`, `white_glove`
`customerId`	string	Conditional	Customer identifier. Either `customerId` or `stripeCustomerId` must be provided.
`stripeCustomerId`	string	Conditional	Stripe customer ID. Either `customerId` or `stripeCustomerId` must be provided.
`subscriptionId`	string	No	Stripe subscription ID

Response

{
  "success": true,
  "customerId": "cus_abc123",
  "subscriptionId": "sub_xyz",
  "tier": "solo",
  "resources": {
    "memory": "2g",
    "cpus": "1"
  }
}

Plan resource allocations

Tier	Memory	CPUs	Notes
`solo`	2 GB	1
`collective`	4 GB	2
`label`	8 GB	4
`network`	16 GB	4
`underground`	2 GB	1	Legacy alias
`starter`	2 GB	1	Legacy alias
`pro`	4 GB	2	Legacy alias
`scale`	8 GB	4	Legacy alias
`enterprise`	16 GB	4	Legacy alias
`white_glove`	32 GB	8	Legacy alias

Errors

Code	Description
400	`customerId` is required (when neither customer ID field is provided)
400	`tier` is required
400	Invalid tier
401	Unauthorized — missing or invalid bearer token
500	Subscription activation failed

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Billing API

Billing API

Get billing info

Response

Response fields

Errors

Billing actions

Create checkout session

Request body

Response

Errors

Enable BYOK

Request body

Response

Errors

Disable BYOK

Request body

Response

Get usage

Request body

Response

Buy credits

Request body

Response

Errors

Common errors

Subscription deploy

Request body

Response

Plan resource allocations

Errors

​Billing API

​Get billing info

​Response

​Response fields

​Errors

​Billing actions

​Create checkout session

​Request body

​Response

​Errors

​Enable BYOK

​Request body

​Response

​Errors

​Disable BYOK

​Request body

​Response

​Get usage

​Request body

​Response

​Buy credits

​Request body

​Response

​Errors

​Common errors

​Subscription deploy

​Request body

​Response

​Plan resource allocations

​Errors

Billing API

Get billing info

Response

Response fields

Errors

Billing actions

Create checkout session

Request body

Response

Errors

Enable BYOK

Request body

Response

Errors

Disable BYOK

Request body

Response

Get usage

Request body

Response

Buy credits

Request body

Response

Errors

Common errors

Subscription deploy

Request body

Response

Plan resource allocations

Errors