Client API
SDK-facing routes called by @amba/client on end-user devices.
Everything under /client is what end-user devices hit via the @amba/client SDK. Every request requires the project's client API key in X-Api-Key. After a user signs in, the SDK attaches the session token as a Bearer.
Shape
/client/auth/* and /client/config accept requests with only X-Api-Key. All other client routes require both headers.
Modules
| Module | Prefix | Purpose |
|---|---|---|
| auth | /client/auth | Anonymous, Apple, Google, email signup / login / link, refresh, logout. |
| sync | /client/sync | Multi-module delta sync for background refresh. |
| events | /client/events | Single endpoint POST /client/events for Amba.track(). |
| users | /client/users | Current user profile + push-token registration. |
| config | /client/config | Evaluated remote-config bundle (ETag-aware). |
| entitlements | /client/entitlements | Current user's active entitlements. |
| content | /client/content | Today's content, library reads, user-owned item CRUD. |
| streaks | /client/streaks | Read streaks, qualify a streak. |
| xp | /client/xp | XP, history, rules. |
| achievements | /client/achievements | Achievement list + single lookup with progress. |
| challenges | /client/challenges | Active challenges, join, user's own. |
| leaderboards | /client/leaderboards | Leaderboard list, entries, user's rank. |
| currencies | /client/currencies | Balances + transactions. |
| catalog | /client/catalog | Catalog browsing. |
| stores | /client/stores | Storefront listings. |
| inventory | /client/inventory | Owned items, purchase, consume. |
| referrals | /client/referrals | User's referral code + redemption. |
| feeds | /client/feeds | Personalized and group feeds. |
| friends | /client/friends | Friend requests + lifecycle. |
| groups | /client/groups | Create, search, join, leave, members. |
| messaging | /client/messaging | Conversations, messages, read receipts. |
| reviews | /client/reviews | Submit + edit + fetch reviews. |
| moderation | /client/moderation | User-initiated reports. |
| onboarding | /client/onboarding | Onboarding state machine. |
| deep-links | /client/deep-links | Slug resolution + click tracking. |
| media | /client/media | Read media + upload. |
| roles | /client/roles | Current user's roles + permissions. |
| sessions | /client/sessions | Session lifecycle (start / end / heartbeat). |
Common errors
| Code | Status | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid X-Api-Key / session token. |
TOKEN_EXPIRED | 401 | Session token expired — call POST /client/auth/refresh. |
NOT_FOUND | 404 | Resource does not exist or isn't owned by the current user. |
INVALID_INPUT | 400 | Request body failed validation. |
RATE_LIMITED | 429 | Too many requests — back off. |