Workspaces & Balance

A workspace is the unit of isolation and billing in Runne Pass. It owns the balance, the API keys, the quota, and the usage history.

Create a workspace

curl -b cookies.txt -X POST https://api.runne.run/v1/workspaces \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-app"}'

name is required (min 1 char). Response (HTTP 201):

{
  "id": "0191…",
  "customer_id": "0191…",
  "name": "my-app",
  "balance": "0",
  "currency": "RUB",
  "status": "active",
  "created_at": "…",
  "updated_at": "…"
}

A workspace starts with balance: "0", currency: "RUB", and status: "active". Creating it also inserts an owner membership row for the customer, in a single transaction.

List workspaces

curl -b cookies.txt https://api.runne.run/v1/workspaces

{ "workspaces": [ { "id": "0191…", "customer_id": "0191…", "name": "my-app", "balance": "0", "currency": "RUB", "status": "active", "created_at": "…", "updated_at": "…" } ] }

Only workspaces owned by the current customer are returned.

Ownership and IDOR protection

Every workspace-scoped endpoint resolves the customer from the session and checks that the requested workspace_id belongs to that customer:

workspace.customer_id == session.customer_id

A mismatch returns 403 (or 404 on some endpoints). Non-UUID workspace_id values resolve to "not owned" instead of raising a database cast error. Because ownership is checked on every mutation, you cannot read or mutate another customer's workspace by guessing IDs.

Balance

The balance is stored as a decimal string (in tokens) on the workspace row, not as a floating-point number. Treat it as opaque text; never parse it into a float.

curl -b cookies.txt https://api.runne.run/v1/workspaces/WORKSPACE_ID/balance

{ "balance": "0", "updated_at": "…" }

The same data is available through the API-key surface at GET /v1/balance (scope balance:read), which additionally returns currency.

How the balance changes

• Credit — top-up via a successful payment (webhook).
• Reservation / settlement / refund — chat completions.
• Adjustment — admin-initiated correction.
• Debit — deficit settlement when a request costs more than estimated.

Every change writes a ledger row — see Architecture and Errors for the 402 insufficient_balance behavior.

Workspace status

Status	Meaning
active	Normal operation
suspended	Blocks API-key requests (403) and suspends session access; set automatically when a deficit cannot be debited, or by an admin
archived	Retired

A suspended workspace (or a suspended customer) is rejected by the gateway before any request is processed.

Related

• API Keys — keys belong to a workspace.
• Rate Limits & Quotas — quota is workspace-scoped.
• Payments & YooKassa — fund a workspace.