KAIRO integration API

SAVORAFUN holds the token balances. KAIRO calls these endpoints server-side with an API key created in the admin console. Never expose the key in browser code.

Authentication

Send the key in the x-api-key header on every request.

x-api-key: sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Check balance

POST /api/public/kairo/v1/balance

{ "email": "user@example.com" }

→ 200 { "ok": true, "balance": 9450 }

Spend tokens

Pass a unique reference per usage event — retries with the same reference are ignored, so a network hiccup never double-charges a user.

POST /api/public/kairo/v1/spend

{
  "email": "user@example.com",
  "tokens": 120,
  "reason": "chat_completion",
  "reference": "kairo-run-8f21c"
}

→ 200 { "ok": true, "balance": 9330 }
→ 402 { "error": "insufficient_tokens", "balance": 40 }

Out of tokens?

On a 402, redirect the user to this store. They return to KAIRO with a topped-up balance immediately after payment clears.

https://savorafun.lovable.app/#packs