— Developer Portal

ZeroFall Game API

Public REST endpoints for the ZeroFall mobile client. Everything is scoped to the signed-in player through Lovable Cloud auth and row-level security.

Authentication

All player-scoped endpoints require the caller to send the player's Supabase JWT as Authorization: Bearer <access_token>. Public content endpoints do not require a token.

Get a token from the mobile client using the shared Supabase project keys:

const { data } = await supabase.auth.signInWithPassword({ email, password });
const token = data.session?.access_token;
await fetch("https://<your-domain>/api/public/game/me", {
  headers: { Authorization: `Bearer ${token}` },
});

Base URL & CORS

All endpoints are same-origin under this site's host. CORS is enabled for all origins with the standard preflight (OPTIONS).

Content (public, no auth)

GET/api/public/game/news

Published news feed.

GET/api/public/game/announcements

Active in-game announcements.

Player account

GET/api/public/game/meBearer

Public profile + player profile.

GET/api/public/game/betaBearer

Beta access status.

Character

GET/api/public/game/characterBearer

Character loadout, faction, and stats.

PUT/api/public/game/characterBearer

Partial update of character/faction/stats.

{ "character": {...}, "faction": "wardens", "stats": {...} }

Progression (level, XP, survival stats)

GET/api/public/game/progressionBearer

Level, XP, currency, playtime, kills, distance, bases, vehicles.

PATCH/api/public/game/progressionBearer

Sync counters from the client. Only whitelisted numeric fields are accepted.

{ "level": 12, "xp": 5400, "playtime_seconds": 8210, "zombies_defeated": 300 }

Inventory

GET/api/public/game/inventoryBearer

All inventory items for the player.

POST/api/public/game/inventoryBearer

Grant an item to the player.

{ "name": "Salvaged Rifle", "category": "weapon", "rarity": "rare", "quantity": 1 }

Achievements

GET/api/public/game/achievementsBearer

Full catalog + unlocked entries for player.

POST/api/public/game/achievementsBearer

Unlock or update progress for a single achievement.

{ "achievement_id": "first_blood", "progress": 100 }

Social

GET/api/public/game/friendsBearer

All friendship rows involving the player.

GET/api/public/game/clanBearer

Player's clan, role, and member list.

Notifications

GET/api/public/game/notificationsBearer

Most recent 100 notifications.

PATCH/api/public/game/notificationsBearer

Mark notifications as read/unread.

{ "ids": ["uuid1","uuid2"], "read": true }

Game settings

GET/api/public/game/settingsBearer

Language, region, graphics, audio, controls, preferences.

PUT/api/public/game/settingsBearer

Partial update of settings.

{ "language": "en", "graphics_quality": "high", "sfx_volume": 0.8 }

Cloud saves

GET/api/public/game/savesBearer

All save slots. Use ?slot=N to fetch one.

PUT/api/public/game/savesBearer

Create or replace a save slot (max 2 MB payload).

{ "slot": 0, "label": "Sector 7", "version": 1, "payload": {...}, "checksum": "sha256:..." }
DELETE/api/public/game/saves?slot=0Bearer

Delete a save slot.

Errors

Errors are JSON in the form { "error": "message" }. Common statuses: 401 missing/invalid token, 400 bad input, 413 payload too large, 500 upstream failure.

Data model

The mobile game and the website share the same database. All rows are protected by row-level security so a token only ever sees its own data. Tables the game will use: profiles, player_profiles, inventory_items, achievements, user_achievements, friendships, clans, clan_members, notifications, game_settings, cloud_saves, news, announcements.