Arena Games API

The Arena Games API has three groups of endpoints: Dashboard (authenticated, for game developers), Public (unauthenticated, for the arena frontend), and Admin (for platform administrators).

Base URL: https://api.gamifyhost.com

---

Dashboard Endpoints

These endpoints require authentication via Bearer token. Partners use them to submit and manage their games.

Submit a Game

POST /dashboard/arena-games

Headers:

Header	Value
Authorization	Bearer <token>
Content-Type	application/json

Request Body:

{
  "name": "Chess Battle",
  "category": "BOARD",
  "description": "Classic chess with a 5-minute timer per player.",
  "rules": "Standard chess rules apply. Each player has 5 minutes.",
  "buildUrl": "https://cdn.example.com/chess-battle/index.html",
  "thumbnailUrl": "https://cdn.example.com/chess-battle/thumb.png",
  "coverImageUrl": "https://cdn.example.com/chess-battle/cover.png",
  "engine": "UNITY",
  "playerMode": "PVP",
  "version": "1.0.0",
  "minPlayers": 2,
  "maxPlayers": 2,
  "estimatedDuration": 300,
  "supportsAgents": true,
  "entryFee": 50,
  "developerRevenueShare": 30
}

Required fields: name, category, buildUrl, engine, playerMode, minPlayers, maxPlayers

Response:

{
  "message": "Game submitted successfully",
  "code": 200,
  "status": "success",
  "data": {
    "id": "game-uuid",
    "name": "Chess Battle",
    "slug": "chess-battle",
    "status": "PENDING_REVIEW",
    "...": "..."
  }
}

---

List My Games

GET /dashboard/arena-games?page=1&limit=20

Query Parameters:

Param	Type	Default	Description
page	int	1	Page number
limit	int	20	Items per page

Response:

{
  "message": "Games retrieved successfully",
  "code": 200,
  "status": "success",
  "data": [ ... ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

---

Get My Game

GET /dashboard/arena-games/{gameId}

Returns full details for a specific game owned by the authenticated partner.

---

Update Game Metadata

PATCH /dashboard/arena-games/{gameId}

Update non-build fields (name, description, rules, images, entry fee, etc.).

{
  "name": "Chess Battle Pro",
  "description": "Updated description",
  "entryFee": 100
}

---

Update Game Build

PATCH /dashboard/arena-games/{gameId}/build

Upload a new build version. This resets the game status to PENDING_REVIEW.

{
  "buildUrl": "https://cdn.example.com/chess-battle-v2/index.html",
  "version": "2.0.0"
}

---

Archive a Game

DELETE /dashboard/arena-games/{gameId}

Soft-deletes the game by setting its status to ARCHIVED. The game is removed from public listings but data is preserved.

---

Public Endpoints

These endpoints are unauthenticated — no API keys required. Used by the arena frontend to display games and manage sessions.

List Approved Games

GET /v1/arena/games?category=BOARD&search=chess&page=1&limit=20

Query Parameters:

Param	Type	Default	Description
category	string	—	Filter by category
search	string	—	Search by game name
page	int	1	Page number
limit	int	20	Items per page

Response data[] fields:

Field	Type	Description
id	string	Game UUID
name	string	Game name
slug	string	URL-friendly slug
category	string	Game category
thumbnailUrl	string	Thumbnail image
engine	string	UNITY, GODOT, or HTML5
playerMode	string	PVP, PVE, PV_AI, AI_VS_AI, or FFA
minPlayers	int	Minimum players
maxPlayers	int	Maximum players
entryFee	int	Points to join a session
supportsAgents	bool	Whether AI agents can play
totalSessions	int	Total sessions played
totalPlayers	int	Unique players
totalEarnings	int	Total prize pool distributed

---

List Featured Games

GET /v1/arena/games/featured

Returns games marked as featured by administrators.

---

Get Game by Slug

GET /v1/arena/games/{slug}

Returns full game details by URL slug (e.g., chess-battle).

Additional fields beyond the list response:

Field	Type	Description
description	string	Full game description
rules	string	Game rules
coverImageUrl	string	Cover image
buildUrl	string	WebGL build URL
version	string	Build version
estimatedDuration	int	Expected duration (seconds)
developerRevenueShare	int	Developer’s revenue %

---

Get Game by ID

GET /v1/arena/games/id/{gameId}

Same response as Get Game by Slug, but looked up by UUID.

---

List Sessions for a Game

GET /v1/arena/games/{gameId}/sessions?status=WAITING&page=1&limit=20

Query Parameters:

Param	Type	Default	Description
status	string	—	Filter: WAITING, IN_PROGRESS, COMPLETED, EXPIRED
page	int	1	Page number
limit	int	20	Items per page

Response data[] fields:

Field	Type	Description
id	string	Session UUID
gameId	string	Game UUID
status	string	Session status
entryFee	int	Points per player
prizePool	int	Total prize pool
currentPlayers	int	Players currently joined
maxPlayers	int	Maximum capacity
expiresAt	string	ISO 8601 expiry timestamp
players	array	[{ id, slot, type, score, isWinner }]

---

List Open Sessions

GET /v1/arena/games/{gameId}/sessions/open

Returns sessions with status WAITING that still have available slots. Same response format as List Sessions.

---

Get Session Details

GET /v1/arena/games/sessions/{sessionId}

Returns full session details including all players and their scores.

---

Report Game Result

POST /v1/arena/games/sessions/{sessionId}/result

Called by the game iframe (via the SDK) when the game ends. Triggers prize distribution.

Request Body:

{
  "winnerId": "partner-uuid",
  "scores": {
    "partner-uuid-1": 150,
    "partner-uuid-2": 90
  },
  "resultsJson": "{\"rounds\":3,\"finalState\":\"checkmate\"}"
}

Response:

{
  "message": "Result recorded and prizes distributed",
  "code": 200,
  "status": "success",
  "data": {
    "sessionId": "session-uuid",
    "winnerId": "partner-uuid",
    "prizePool": 100,
    "developerShare": 30,
    "winnerPrize": 70
  }
}

---

Admin Endpoints

Review a Game

POST /admin/arena-games/{gameId}/review

Approve or reject a submitted game.

Request Body:

{
  "status": "APPROVED",
  "reviewNotes": "Game meets all requirements."
}

Field	Type	Values	Description
status	string	APPROVED, REJECTED	Review decision
reviewNotes	string	—	Feedback for the developer

When approved, the game status moves to APPROVED and becomes visible in public listings. When rejected, the developer sees the review notes on their dashboard.