Resources

API reference

Most integrations never call these directly — the SDK and React components wrap them. This is what's underneath.

Base URL

https://www.crediball.ai/api for the hosted product, or /api on your own deployment.

Authentication

Every request carries an API key as a bearer token: Authorization: Bearer cb_live_… (secret key, server-side only, full read/write access) or Authorization: Bearer cb_pub_… (publishable key, safe for the browser, read-only). Some publishable-key GET endpoints also accept the key as a ?key=cb_pub_… query parameter. Secret-key endpoints additionally accept the key via an x-api-key header.

Secret-key endpoints (server-side)

POST	/api/credits/charge	Deduct credits for an action (what crediball.action()/track() call under the hood)
POST	/api/credits/topup	Grant credits to a user
POST	/api/events/track	Record an action event
POST	/api/events/usage	Report AI model token usage
POST	/api/actions/declare	Register action keys ahead of first use (the sync CLI's endpoint)
POST	/api/topup/checkout	Create a Stripe Checkout session for a top-up package
POST	/api/subscriptions/subscribe	Start a subscription plan for a user
POST	/api/subscriptions/cancel	Cancel a user's subscription
POST	/api/promotions/grant	Grant a promotional credit bonus
POST	/api/promotions/redeem	Redeem a promo code for a user
POST	/api/referral/complete	Mark a referral's conversion condition as met

Publishable-key endpoints (browser-safe)

GET	/api/public/balance	A user's current credit balance
GET	/api/public/usage	A user's usage history
GET	/api/public/costs	The live cost list for every active action
GET	/api/public/packages	Top-up packages, subscription plans, and the signup bonus
GET	/api/public/referral	A user's referral link, clicks, and rewards
POST	/api/public/topup/checkout	Start a Stripe Checkout session from the browser
POST	/api/public/subscriptions/checkout	Start a subscription checkout from the browser

These are exactly what @crediball/react’s useCrediball() and @crediball/elements call on your behalf with CORS enabled, so you rarely need to call them yourself.