Docs / Protocols / REST

REST API

All endpoints are under /api/v1. Requests and responses are JSON. Authenticated endpoints require Authorization: Bearer .

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 (never the last one)

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/:id            Accept / reject / block
DELETE /api/v1/friends/:id            Remove friend

POST   /api/v1/groups                 Create group
GET    /api/v1/groups/:id             Get group
POST   /api/v1/groups/:id/join        Join group
POST   /api/v1/groups/:id/leave       Leave group

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 a store listing
GET  /api/v1/inventory                 List player items
POST /api/v1/inventory/consume         Consume an item

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

Leaderboards & tournaments

GET  /api/v1/leaderboards/:id                  Top N entries
GET  /api/v1/leaderboards/:id/around/:player   Entries around a player
POST /api/v1/leaderboards/:id                  Submit a score

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

Matchmaking

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

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

Chat

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

Notifications

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

Storage

GET    /api/v1/saves                              List save slots
GET    /api/v1/saves/:slot                        Get save data
PUT    /api/v1/saves/:slot                        Write save (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

Typical curl example

# login
curl -s -X POST http://localhost:8082/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "player1", "password": "secret123"}' > /tmp/login.json
TOKEN=$(jq -r .session_token /tmp/login.json)

# submit a matchmaking ticket
curl -X POST http://localhost:8082/api/v1/matchmaker \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mode": "arena", "properties": {"skill": 1200}}'

Real-time flows go over WebSocket. Matchmaking notifications, chat, votes, presence, and live state updates are on the WebSocket protocol. Use REST for request/response; use WS for push + low-latency interactions.

Where next?