Nurama Developers
AI

Get the workspace's current Nurama Credit balance.

Returns the workspace's spendable Nurama Credit balance, sourced from the canonical `CreditBalance` row maintained atomically by the AI usage and grant flows. Requires `canGetCreditBalance` on the workspace (workspace owner / admin, project owner / admin) and an active subscription; no per-feature gate. The balance is also returned as `balanceAfter` on every billable AI call, so the FE can keep its display fresh without a separate fetch after every call. `balance` is the spendable total: `planBalance` (monthly plan grant, does not carry over) + `purchasedBalance` (top-ups, accumulates). `hasPriorTopUp` reports whether the workspace has ever made a manual credit purchase — the precondition for enabling auto top-up. Aliased at `GET /credits/balance` (same handler, same response).

GET
/ai/balance

Returns the workspace's spendable Nurama Credit balance, sourced from the canonical CreditBalance row maintained atomically by the AI usage and grant flows.

Requires canGetCreditBalance on the workspace (workspace owner / admin, project owner / admin) and an active subscription; no per-feature gate. The balance is also returned as balanceAfter on every billable AI call, so the FE can keep its display fresh without a separate fetch after every call.

balance is the spendable total: planBalance (monthly plan grant, does not carry over) + purchasedBalance (top-ups, accumulates). hasPriorTopUp reports whether the workspace has ever made a manual credit purchase — the precondition for enabling auto top-up.

Aliased at GET /credits/balance (same handler, same response).

Authorization

AuthorizationBearer <token>

OAuth 2.1 authorization code flow with PKCE (required of every client, public or confidential). Scopes are a ceiling on the credential, not a grant of access: a token also cannot exceed what the user who approved it may already do. A write scope does not imply its matching read — ask for both.

In: header

Scope: ai:use

Query Parameters

workspaceId*string

Workspace whose Nurama Credit balance to retrieve.

Formatuuid

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/ai/balance?workspaceId=497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "balance": 9997,  "planBalance": 5000,  "purchasedBalance": 4997,  "hasPriorTopUp": true}