Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt

Use this file to discover all available pages before exploring further.

All endpoints under /v1/sub-accounts require a main account API key. A sub-account API key calling these endpoints receives HTTP 403. Sub-accounts can read their own balance via GET /v1/balance.

​
List Sub-Accounts

const { items, nextCursor } = await zavu.subAccounts.list({
  limit: 50,
});

for (const sub of items) {
  console.log(`${sub.name}: $${(sub.totalSpent / 100).toFixed(2)} spent`);
}

​
Update a Sub-Account

Update the name, credit limit, external ID, metadata, or status: 
const { subAccount } = await zavu.subAccounts.update("jx7abc123def456", {
  creditLimit: 200000, // Increase to $2,000
  metadata: { plan: "enterprise-plus" },
});

​
Updatable Fields

FieldTypeDescription
namestringSub-account display name
externalIdstringYour reference ID
creditLimitinteger | nullSpending cap in cents. Set to null or 0 to remove
metadataobjectArbitrary key-value data
statusstring"active" or "inactive"

​
Monitor Spending

​
Check a Sub-Account’s Balance

const balance = await zavu.subAccounts.getBalance("jx7abc123def456");

console.log(`Team balance: $${(balance.balance / 100).toFixed(2)}`);
console.log(`Sub-account spent: $${(balance.totalSpent / 100).toFixed(2)}`);
console.log(`Credit limit: $${(balance.creditLimit / 100).toFixed(2)}`);
Response: 
{
  "balance": 150000,
  "currency": "usd",
  "creditLimit": 100000,
  "totalSpent": 45000,
  "isSubAccount": true
}

​
Check Balance from the Sub-Account’s Perspective

When a sub-account uses its own API key to call GET /v1/balance, it sees the team balance plus its own spending data: 
curl https://api.zavu.dev/v1/balance \
  -H "Authorization: Bearer zv_live_sub_xxxxxxxxxxxx"

{
  "balance": 150000,
  "currency": "usd",
  "creditLimit": 100000,
  "totalSpent": 45000,
  "isSubAccount": true
}

​
Manage API Keys

Each sub-account can have multiple API keys. Create additional keys or revoke compromised ones.

​
List API Keys

const { items } = await zavu.subAccounts.listApiKeys("jx7abc123def456");

for (const key of items) {
  console.log(`${key.name} (${key.keyPrefix}...): ${key.environment}`);
}

​
Create an API Key

const { apiKey } = await zavu.subAccounts.createApiKey("jx7abc123def456", {
  name: "Production Key",
  environment: "live",
});

// Save this — only shown once
console.log("New key:", apiKey.key);
The full API key is only returned once in the creation response. Store it securely.

​
Revoke an API Key

await zavu.subAccounts.revokeApiKey("jx7abc123def456", "key_id_here");
Revoked keys stop working immediately.

​
Suspend a Sub-Account

Set a sub-account’s status to inactive to temporarily block all messaging without revoking API keys: 
curl -X PATCH https://api.zavu.dev/v1/sub-accounts/jx7abc123def456 \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'
Re-activate later by setting status back to "active".

​
Next Steps

Deletion & Deactivation

Permanently deactivate sub-accounts

Sub-Accounts Concept

Understand the billing model and architecture