Concepts

Open-default routing (the margin engine)

Bulk traffic goes to cheap open models; frontier models fire only on a real signal (difficulty / retry / explicit). You see the lane + model + cost on every run. This is what keeps Koda affordable — never routed frontier-by-default.

Prepaid wallet + minor units

Balances and costs are integer minor units (kobo for NGN); fields are named *Minor. Each run debits the wallet and returns the new balance. Top up on any local rail. A run with no balance returns 402.

Major vs minor. A few inputs take major units and say so: topup(amountNaira) and member capNaira are Naira, converted server-side. Everything else (amountMinor, balanceMinor, costMinor) is minor.

Subscriptions + included usage

Plans grant a tier + a monthly included-usage allowance; the wallet is the overage / pay-as-you-go. Metering draws from the allowance first, then the wallet.

Idempotency

Wallet-mutating calls accept an Idempotency-Key header (per user) — retries never double-charge.

Org-scoped retrieval

Index your repo (/repo/index); the agent retrieves the most relevant chunks per task, isolated per org. Requires the gateway in vector mode.

Auth

Browsers use a sealed session cookie; programmatic clients use API keys (scopes). Native auth supports password, magic-link, TOTP MFA, and enterprise SSO (OIDC/SAML).

Rate limits & residency

Per-IP rate limits (four buckets); over-limit ⇒ 429 + Retry-After + RateLimit-*. Enterprise orgs can pin a serving region and move their data into a dedicated schema.

Errors

Errors are { "error": "message" }. Common codes: 401 unauth · 402 top-up required · 403 scope/role · 429 rate-limited · 451 residency · 503 not-configured. Agent + chat endpoints stream Server-Sent Events.