REST API

All endpoints are under /api/v1. Requests and responses use JSON.

Authenticated endpoints require the Authorization: Bearer <session_token> header.

Auth

POST   /api/v1/auth/register     Register a new player
POST   /api/v1/auth/login        Login, returns session token
POST   /api/v1/auth/refresh      Refresh session token
POST   /api/v1/auth/oauth        OAuth / Steam token validation
POST   /api/v1/auth/link         Link a provider to the current account
DELETE /api/v1/auth/unlink       Unlink a provider

Register

curl -X POST /api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"username": "player1", "password": "secret123", "display_name": "Player One"}'

{"player_id": "...", "session_token": "...", "username": "player1"}

Login

curl -X POST /api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "player1", "password": "secret123"}'

{"player_id": "...", "session_token": "...", "username": "player1"}

Players

GET /api/v1/players/:id        Get player profile
PUT /api/v1/players/:id        Update own profile

Social

GET    /api/v1/friends                               List friends
POST   /api/v1/friends                               Send friend request
PUT    /api/v1/friends/:friend_id                    Accept/reject/block
DELETE /api/v1/friends/:friend_id                    Remove friend

POST   /api/v1/groups                                Create group
GET    /api/v1/groups/:id                            Get group
PUT    /api/v1/groups/:id                            Update group
POST   /api/v1/groups/:id/join                       Join group
POST   /api/v1/groups/:id/leave                      Leave group
GET    /api/v1/groups/:id/members                    List group members
PUT    /api/v1/groups/:id/members/:player_id/role    Update member role
DELETE /api/v1/groups/:id/members/:player_id         Kick member

Economy

GET  /api/v1/wallets                   List player wallets
GET  /api/v1/wallets/:currency/history Transaction history
GET  /api/v1/store                     List store catalog
POST /api/v1/store/purchase            Purchase item
GET  /api/v1/inventory                 List player items
POST /api/v1/inventory/consume         Consume item

POST /api/v1/iap/apple                 Validate an Apple receipt
POST /api/v1/iap/google                Validate a Google Play receipt

Leaderboards

GET  /api/v1/leaderboards/:id                  Top N entries
GET  /api/v1/leaderboards/:id/around/:player_id Around player
POST /api/v1/leaderboards/:id                  Submit score

Matchmaking

POST   /api/v1/matchmaker              Submit matchmaking ticket
GET    /api/v1/matchmaker/:ticket_id   Check ticket status
DELETE /api/v1/matchmaker/:ticket_id   Cancel ticket

Tournaments

GET  /api/v1/tournaments               List active tournaments
GET  /api/v1/tournaments/:id           Get tournament details
POST /api/v1/tournaments/:id/join      Join tournament

Votes

GET /api/v1/matches/:match_id/votes    List votes for a match (newest first, max 50)
GET /api/v1/votes/:id                  Get a single vote with full results

Voting itself happens over WebSocket. See the Voting guide.

Chat

GET /api/v1/chat/:channel_id/history   Message history (paginated)

Real-time chat messages are sent and received over WebSocket.

Notifications

GET    /api/v1/notifications           List notifications (paginated)
PUT    /api/v1/notifications/:id/read  Mark as read
DELETE /api/v1/notifications/:id       Delete notification

Direct messages

POST /api/v1/dm                        Send a direct message
GET  /api/v1/dm/:player_id/history     DM history with a player

Storage

GET    /api/v1/saves                   List save slots
GET    /api/v1/saves/:slot             Get save data
PUT    /api/v1/saves/:slot             Write save (with version for OCC)

GET    /api/v1/storage/:collection             List objects
GET    /api/v1/storage/:collection/:key        Read object
PUT    /api/v1/storage/:collection/:key        Write object
DELETE /api/v1/storage/:collection/:key        Delete object