# Cloud API Documentation **Server**: `cloud/cloud_api/cloud_api.ts` **Port**: 3002 **Purpose**: Multiplayer, rooms, social, and real-time features for Bigscreen VR app ## Overview The Cloud API handles: - Real-time multiplayer rooms - Social features (friends, notifications, blocking) - Screen sharing and media sessions - Activities and presence - Channels and lobbies - WebSocket connections for real-time communication ## Authentication ### Required Headers All endpoints require: ``` Authorization: ``` Most public endpoints also require: ``` Authorization: Bearer ``` Admin endpoints require moderator access policy. ### Authentication Types - **Bearer + Access Token**: Most public endpoints - **Moderator**: Admin endpoints - **Website Auth**: Browser endpoints (website only) - **Hyperbeam Bearer**: Hyperbeam webhooks - **Media Server**: Media server registration --- ## Endpoints ### Admin Functions **Auth**: Moderator access policy required #### Get Realtime Statistics ``` GET /admin/statistics ``` **Returns**: Real-time server statistics #### Get Schemas ``` GET /admin/schemas ``` **Returns**: Cloud API schemas --- ### Rooms Admin #### Create Admin Room ``` POST /admin/room ``` **Body**: Room details **Returns**: New room #### Get Room ``` GET /admin/room/:roomId ``` **Returns**: Room details #### Get Live Room Instance ``` GET /admin/room/:roomId/live ``` **Returns**: Live room state #### Get Room History ``` GET /admin/room/:roomId/history ``` **Returns**: Room access history #### Update Room ``` PUT /admin/room/:roomId ``` **Body**: Room updates **Returns**: Updated room #### Kick User ``` GET /admin/room/:roomId/users/:userSessionId/kick ``` **Returns**: Kick confirmation #### Eject User ``` GET /admin/room/:roomId/users/:userSessionId/eject ``` **Returns**: Eject confirmation #### Delete Room ``` DELETE /admin/room/:roomId ``` **Returns**: Deletion confirmation #### Get All Live Rooms ``` GET /admin/rooms/live ``` **Returns**: All active rooms #### Get Environments ``` GET /admin/rooms/environments ``` **Returns**: Available room environments #### Get All Public Rooms ``` GET /admin/rooms/all ``` **Returns**: All public rooms --- ### Account Admin (Live Users) #### Send Admin Message ``` POST /admin/account/:bigscreenAccountId/message ``` **Body**: Message details **Returns**: Send confirmation #### Get Connections ``` GET /admin/account/:bigscreenAccountId/connections ``` **Returns**: Active connections #### Get Rooms for User ``` GET /admin/account/:bigscreenAccountId/rooms ``` **Returns**: User's rooms #### Disconnect All Connections ``` GET /admin/account/:bigscreenAccountId/disconnect ``` **Returns**: Disconnect confirmation --- ### Network Status (Admin) #### Get All Media Servers ``` GET /admin/network/media-servers ``` **Returns**: All registered media servers #### Get Media Server ``` GET /admin/network/media-server/:mediaServerId ``` **Returns**: Media server details #### Update Media Server ``` PUT /admin/network/media-server/:mediaServerId ``` **Body**: Server updates **Returns**: Updated server #### Search Redis ``` POST /admin/network/redis ``` **Body**: Redis query **Returns**: Query results #### Get Redis Cluster Info ``` GET /admin/network/redis-info ``` **Returns**: Redis cluster information --- ### Screens Admin #### Get Screen ``` GET /admin/screen/:screenId ``` **Returns**: Screen details #### Modify Media Session ``` PUT /admin/screen/:screenId/session ``` **Body**: Session updates **Returns**: Updated session #### Update Screen ``` PUT /admin/screen/:screenId ``` **Body**: Screen updates **Returns**: Updated screen #### Delete Screen ``` DELETE /admin/screen/:screenId ``` **Returns**: Deletion confirmation --- ### Activities Admin #### Create Activity ``` POST /admin/activity ``` **Body**: Activity details **Returns**: New activity #### Get Activity ``` GET /admin/account/:bigscreenAccountId/activity/:activityId ``` **Returns**: Activity details #### Get Activities ``` GET /admin/account/:bigscreenAccountId/activities ``` **Returns**: User's activities #### Update Activity ``` PUT /admin/activity/:activityId ``` **Body**: Activity updates **Returns**: Updated activity #### Delete Activity ``` DELETE /admin/activity/:activityId ``` **Returns**: Deletion confirmation --- ### Social Admin #### Get Profile ``` GET /admin/account/:bigscreenAccountId/social/profile ``` **Returns**: Social profile #### Get All Profiles (Debug) ``` GET /admin/account/:bigscreenAccountId/social_profiles ``` **Returns**: All social profiles (debug) #### Get History ``` GET /admin/account/:bigscreenAccountId/social/history GET /admin/account/:bigscreenAccountId/social/history/:historyItemType ``` **Returns**: Social interaction history #### Get Graph ``` GET /admin/account/:bigscreenAccountId/social/graph GET /admin/account/:bigscreenAccountId/social/graph/:socialGraphType ``` **Returns**: Social graph (friends, blocked, etc.) #### Delete Graph Item ``` DELETE /admin/social/graph/:graphItemId ``` **Returns**: Deletion confirmation #### Get Stats ``` GET /admin/account/:bigscreenAccountId/social/stats ``` **Returns**: Social statistics #### Get Notifications ``` GET /admin/account/:bigscreenAccountId/social/notifications ``` **Returns**: User's notifications #### Create Notification ``` POST /admin/account/:bigscreenAccountId/social/notification ``` **Body**: Notification details **Returns**: New notification #### Delete Notification ``` DELETE /admin/social/notification/:notificationId ``` **Returns**: Deletion confirmation #### Accept Notification ``` GET /admin/social/notification/:notificationId/accept ``` **Returns**: Accept confirmation --- ### Media Server API **Auth**: Media server registration #### Register Media Server ``` POST /api/media-server/register ``` **Body**: Server registration details **Returns**: Registration confirmation #### Get Server Info ``` GET /api/media-server ``` **Returns**: Server information #### Get Manifest ``` GET /api/media-server/manifest ``` **Returns**: Server manifest #### Get Queue Messages ``` GET /api/media-server/messages ``` **Returns**: Pending messages #### Send Message ``` POST /api/media-server/message ``` **Body**: Message details **Returns**: Send confirmation --- ### Public User Functions **Auth**: Bearer token + access token #### Check Connection Status ``` GET /connection ``` **Returns**: Connection status #### Get Schemas ``` GET /schemas ``` **Returns**: Cloud API schemas #### Get Latest Public Rooms ``` GET /rooms/latest ``` **Auth**: Bearer only **Returns**: Latest public rooms #### Join Room with Invite Code ``` POST /rooms/join ``` **Body**: `{ inviteCode }` **Returns**: Room details and join result #### Create Room ``` POST /room ``` **Body**: Room configuration **Returns**: New room #### Update Room ``` PUT /room/:roomId ``` **Body**: Room updates **Returns**: Updated room #### Get Room Info ``` GET /room GET /room/:roomId ``` **Returns**: Room details #### Get User's Rooms ``` GET /rooms ``` **Returns**: User's rooms #### Join Room by ID ``` POST /room/:roomId/join ``` **Returns**: Join result #### Get Room Data ``` GET /room/:roomId/data ``` **Returns**: Room data (key-value store) #### Set Room Data ``` PUT /room/:roomId/data ``` **Body**: `{ key, value }` **Returns**: Updated data #### Delete Room Data ``` DELETE /room/:roomId/data/:key ``` **Returns**: Deletion confirmation #### Update Seat ``` PUT /room/:roomId/seat/:seatIndex ``` **Body**: Seat configuration **Returns**: Updated seat #### Kick User ``` GET /room/:roomId/users/:userSessionId/kick ``` **Returns**: Kick confirmation #### Leave Room ``` GET /room/:roomId/leave ``` **Returns**: Leave confirmation #### Delete Room ``` DELETE /room/:roomId ``` **Returns**: Deletion confirmation --- ### Channel Functions #### Get Channels in Category ``` GET /channels/:version/:name ``` **Params**: `version`, `name` (category) **Returns**: Channels in category #### Get Channel Info ``` GET /channel/info/:channel_id ``` **Returns**: Channel information #### Join Channel ``` POST /channel/join ``` **Body**: Channel details **Returns**: Join result --- ### Media Functions #### Join Media Showing ``` POST /media/join ``` **Body**: Media showing details **Returns**: Join result --- ### Screen Functions (Public) #### Create Screen ``` POST /screen ``` **Body**: Screen configuration **Returns**: New screen #### Get Screen ``` GET /screen/:screenId ``` **Returns**: Screen details #### Get User's Screens ``` GET /screens ``` **Returns**: User's screens #### Update Screen ``` PUT /screen/:screenId ``` **Body**: Screen updates **Returns**: Updated screen #### Get Media Info ``` GET /screen/:screenId/session ``` **Returns**: Media session information #### Update Media Session ``` PUT /screen/:screenId/session ``` **Body**: Media session updates **Returns**: Updated session #### Close Media Session ``` DELETE /screen/:screenId/session ``` **Returns**: Close confirmation #### Share Screen in Room ``` PUT /room/:roomId/screen/:screenId ``` **Returns**: Share confirmation #### Remove Screen from Room ``` DELETE /room/:roomId/screen/:screenId ``` **Returns**: Remove confirmation #### Delete Screen ``` DELETE /screen/:screenId ``` **Returns**: Deletion confirmation --- ### Lobby #### Join Lobby ``` POST /lobby/join ``` **Body**: Lobby preferences **Returns**: Lobby join result --- ### Activities (Public) #### Create Activity ``` POST /activity ``` **Body**: Activity details **Returns**: New activity #### Get Activity ``` GET /activity/:activityId ``` **Returns**: Activity details #### Get User's Activities ``` GET /activities ``` **Returns**: User's activities #### Update Activity ``` PUT /activity/:activityId ``` **Body**: Activity updates **Returns**: Updated activity #### Delete Activity ``` DELETE /activity/:activityId ``` **Returns**: Deletion confirmation --- ### Social Functions #### Get Rooms via Graph ``` GET /social/rooms ``` **Returns**: Rooms with friends/social connections #### Get Recently Encountered Users ``` GET /social/history ``` **Returns**: Recent social interactions #### Get Friends List ``` GET /social/friends ``` **Returns**: User's friends #### Get Blocked Users ``` GET /social/blocked ``` **Returns**: Blocked users list #### Get User Profile ``` GET /social/profile GET /social/profile/:socialId ``` **Returns**: Social profile #### Block User ``` PUT /social/profile/:socialId/block ``` **Returns**: Block confirmation #### Unblock User ``` PUT /social/profile/:socialId/unblock ``` **Returns**: Unblock confirmation #### Send Knock/Invite ``` POST /social/notification ``` **Body**: Notification details (knock, invite, friend request) **Returns**: New notification #### Get Notifications ``` GET /social/notifications ``` **Returns**: User's notifications #### Get Notification ``` GET /social/notification/:notificationId ``` **Returns**: Notification details #### Mark as Read ``` PUT /social/notification/:notificationId/read ``` **Returns**: Updated notification #### Accept Friend/Invite ``` PUT /social/notification/:notificationId/accept ``` **Returns**: Accept confirmation #### Decline ``` PUT /social/notification/:notificationId/decline ``` **Returns**: Decline confirmation #### Delete Notification ``` DELETE /social/notification/:notificationId ``` **Returns**: Deletion confirmation #### Remove Friend ``` GET /social/profile/:socialId/remove_friend ``` **Returns**: Remove confirmation #### Search Profiles ``` POST /social/search ``` **Body**: Search query **Returns**: Matching profiles --- ### Reporting #### Report User ``` POST /report/user ``` **Body**: Report details **Returns**: Report ID #### Report Room ``` POST /report/room ``` **Body**: Report details **Returns**: Report ID --- ### Browser (Unity Only) **Auth**: Unity client access token #### Update Browser Settings ``` PUT /apps/browser/:activityId ``` **Body**: Browser configuration **Returns**: Updated activity --- ### Browser (Website Only) **Auth**: Website authentication #### Get Browser Activity ``` GET /apps/browser/:activityId ``` **Returns**: Browser activity details --- ### Hyperbeam Webhooks **Auth**: Hyperbeam bearer token #### Hyperbeam Access Check ``` POST /hyperbeam/webhook/:activityId ``` **Body**: Webhook payload **Returns**: Access check result --- ## WebSocket Server The Cloud API also includes a WebSocket server for real-time communication: **Server**: `cloud/cloud_api/ws_server.ts` ### Features - Real-time room updates - Presence notifications - Screen sharing synchronization - Social notifications - Media session events ### Connection WebSocket connections are established through the Cloud API and require authentication via access token. --- ## Related Infrastructure ### Cloud Worker **Server**: `cloud/cloud_api/cloud_worker.ts` Background worker that handles: - Room cleanup - Presence management - Notification delivery - Queue processing ### Media Servers #### Media Server (AWS) **Server**: `cloud/cloud_api/media_server_aws.ts` Media server designed specifically for AWS infrastructure. #### Media Server (Next) **Server**: `cloud/cloud_api/media_server_next.ts` Platform-agnostic media server tested on Digital Ocean and AWS. #### Monitor **Server**: `cloud/cloud_api/monitor.ts` Media server monitoring tool for health checks and statistics. --- ## Source Code - **Main server**: `cloud/cloud_api/cloud_api.ts` - **WebSocket server**: `cloud/cloud_api/ws_server.ts` - **Worker**: `cloud/cloud_api/cloud_worker.ts` - **Setup**: `cloud/cloud_api/cloud_setup.ts` - **Tests**: `tests/cloud-api/`, `tests/social/` ## Related Documentation - [API Overview](API_OVERVIEW.md) - [Auth API](AUTH_API.md) - [Admin API](ADMIN_API.md)