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
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
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/..."
}
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
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 |
